@energy8platform/golem 0.2.1 → 0.5.0

package/dist/lib/cli.js

@@ -3,10 +3,10 @@ import { resolve as resolve3 } from "node:path";
 
 // src/editor/server.ts
 import { createServer } from "node:http";
-import { readFile as readFile9, stat as stat3, readdir as readdir3, mkdir as mkdir5, open } from "node:fs/promises";
+import { readFile as readFile10, stat as stat3, readdir as readdir5, mkdir as mkdir7, open } from "node:fs/promises";
 import { watch as fsWatch } from "node:fs";
-import { resolve as resolve2, dirname as dirname7, basename as basename5, extname as extname2, sep, join as join8, relative as relative3 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { resolve as resolve2, dirname as dirname9, basename as basename5, extname as extname2, sep, join as join10, relative as relative3 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/rig-format.ts
 import { z } from "zod";
@@ -65,7 +65,7 @@ function minJacobian(offsets, w, h, samples = 17) {
 var ID_RE = /^[a-z][a-z0-9_]*$/;
 var Id = z.string().regex(ID_RE, "snake_case id");
 var Ease = z.union([
-  z.enum(["linear", "step", "ease_in", "ease_out", "ease_in_out", "back_out", "elastic_out"]),
+  z.enum(["linear", "step", "ease_in", "ease_out", "ease_in_out", "minimum_jerk", "back_out", "elastic_out"]),
   // cubic-bezier control points, same semantics as CSS
   z.object({ bezier: z.tuple([z.number(), z.number(), z.number(), z.number()]) })
 ]);
@@ -97,6 +97,7 @@ var Asset = z.object({
   /** where this layer came from — provenance for agents */
   origin: z.object({
     sourceImage: z.string().optional(),
+    bboxSpace: z.enum(["source", "document"]).optional(),
     /** bbox in source image: [x, y, w, h] */
     bbox: z.tuple([z.number(), z.number(), z.number(), z.number()]).optional(),
     inpainted: z.boolean().default(false),
@@ -119,6 +120,8 @@ var Bone = z.object({
 var Slot = z.object({
   id: Id,
   bone: Id,
+  /** Closed path attachment used as a moving clipping mask. */
+  clip: Id.optional(),
   /** active attachment id; undefined = hidden */
   attachment: Id.optional(),
   alpha: z.number().min(0).max(1).default(1),
@@ -181,6 +184,8 @@ var IkConstraint = z.object({
   order: z.number().int().default(0),
   bones: z.array(Id).min(1),
   target: Id,
+  iterations: z.number().int().min(1).max(1e3).optional(),
+  tolerance: z.number().positive().optional(),
   mix: z.number().default(1),
   softness: z.number().default(0),
   bendPositive: z.boolean().default(true),
@@ -233,7 +238,7 @@ var BoneProp = z.enum(["x", "y", "rotation", "scaleX", "scaleY", "shearX", "shea
 var SlotProp = z.enum(["alpha", "attachment", "z", "color"]);
 var DeformProp = z.string().regex(/^(bulge|bend|sway|squash|p[0-2][0-2][xy]|vertices)$/, "deform prop must be bulge|bend|sway|squash|p<row><col>x|y|vertices");
 var IkProp = z.enum(["mix", "softness", "bendPositive", "compress", "stretch"]);
-var TransformProp = z.enum(["mixRotate", "mixX", "mixY", "mixScaleX", "mixScaleY", "mixShearY"]);
+var TransformProp = z.enum(["mixRotate", "mixX", "mixY", "mixScaleX", "mixScaleY", "mixShearY", "x", "y", "rotation", "scaleX", "scaleY", "shearY"]);
 var PathProp = z.enum(["position", "spacing", "mixRotate", "mixX", "mixY"]);
 var KeyValue = z.union([z.number(), z.string(), z.null(), z.array(z.number()), z.array(z.string())]);
 var Key = z.object({
@@ -242,14 +247,16 @@ var Key = z.object({
   /** easing INTO the next key */
   ease: Ease.default("ease_in_out")
 });
+var Interpolation = { interpolation: z.enum(["segment", "pchip"]).optional() };
 var Track = z.discriminatedUnion("target", [
-  z.object({ target: z.literal("bone"), id: Id, prop: BoneProp, keys: z.array(Key).min(1) }),
-  z.object({ target: z.literal("slot"), id: Id, prop: SlotProp, keys: z.array(Key).min(1) }),
-  z.object({ target: z.literal("deform"), id: Id, prop: DeformProp, keys: z.array(Key).min(1) }),
-  z.object({ target: z.literal("ik"), id: Id, prop: IkProp, keys: z.array(Key).min(1) }),
-  z.object({ target: z.literal("transform"), id: Id, prop: TransformProp, keys: z.array(Key).min(1) }),
-  z.object({ target: z.literal("path"), id: Id, prop: PathProp, keys: z.array(Key).min(1) }),
-  z.object({ target: z.literal("drawOrder"), id: Id.default("order"), prop: z.literal("order").default("order"), keys: z.array(Key).min(1) })
+  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) }),
+  z.object({ target: z.literal("ik"), id: Id, prop: IkProp, ...Interpolation, keys: z.array(Key).min(1) }),
+  z.object({ target: z.literal("transform"), id: Id, prop: TransformProp, ...Interpolation, keys: z.array(Key).min(1) }),
+  z.object({ target: z.literal("path"), id: Id, prop: PathProp, ...Interpolation, keys: z.array(Key).min(1) }),
+  z.object({ target: z.literal("drawOrder"), id: Id.default("order"), prop: z.literal("order").default("order"), ...Interpolation, keys: z.array(Key).min(1) })
 ]);
 var Event = z.object({
   t: z.number().nonnegative(),
@@ -265,6 +272,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),
@@ -290,7 +316,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;
@@ -365,6 +393,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((s2) => s2.id));
@@ -391,6 +421,10 @@ function validate(doc) {
     if (a.frame && !a.trim && !a.rotate && (a.frame[2] !== a.width || a.frame[3] !== a.height)) errs.push(`asset "${a.id}": frame size must equal width\xD7height (or declare trim/rotate)`);
   }
   for (const s2 of doc.slots) {
+    if (s2.clip) {
+      const mask = attachments.get(s2.clip);
+      if (mask?.type !== "path" || !mask.closed) errs.push(`slot "${s2.id}": clip must name a closed path attachment`);
+    }
     if (!bones.has(s2.bone)) errs.push(`slot "${s2.id}": unknown bone "${s2.bone}"`);
     if (s2.attachment) {
       const a = attachments.get(s2.attachment);
@@ -422,7 +456,8 @@ function validate(doc) {
     }
   }
   for (const c of doc.ik) {
-    if (c.bones.length > 2) errs.push(`ik "${c.id}": must have 1 or 2 bones`);
+    for (let i = 1; i < c.bones.length; i++) if (doc.bones.find((b) => b.id === c.bones[i])?.parent !== c.bones[i - 1])
+      errs.push(`ik "${c.id}": bones must form a contiguous parent-to-child chain`);
     for (const b of c.bones) if (!bones.has(b)) errs.push(`ik "${c.id}": unknown bone "${b}"`);
     if (!bones.has(c.target)) errs.push(`ik "${c.id}": unknown target bone "${c.target}"`);
   }
@@ -434,13 +469,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((s2, a) => s2 + 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;
@@ -448,6 +517,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") {
@@ -487,9 +560,9 @@ function parse(input) {
 }
 
 // src/rig-api.ts
-import { z as z2 } from "zod";
-import { readFile as readFile8, writeFile as writeFile6, stat as stat2 } from "node:fs/promises";
-import { dirname as dirname6, join as join7, relative as relative2, isAbsolute } from "node:path";
+import { z as z3 } from "zod";
+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
 import { mkdir, rename, rm, writeFile } from "node:fs/promises";
@@ -536,6 +609,65 @@ async function withRigQueue(path, op) {
   }
 }
 
+// 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 = {
@@ -544,6 +676,7 @@ var named = {
   ease_in: (t) => t * t,
   ease_out: (t) => 1 - (1 - t) * (1 - t),
   ease_in_out: (t) => t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2,
+  minimum_jerk: (t) => t * t * t * (10 + t * (-15 + 6 * t)),
   back_out: (t) => 1 + 2.70158 * (t - 1) ** 3 + 1.70158 * (t - 1) ** 2,
   elastic_out: (t) => t === 0 ? 0 : t === 1 ? 1 : 2 ** (-10 * t) * Math.sin((t * 10 - 0.75) * (2 * Math.PI / 3)) + 1
 };
@@ -575,7 +708,25 @@ function ease(spec) {
   return f;
 }
 var pk = (target, id, prop) => `${target}:${id}:${prop}`;
-function sample(track, t) {
+function smoothValue(track, i, t, component, loop) {
+  const k = track.keys, n = k.length;
+  const v = (j2) => component === void 0 ? k[j2].v : k[j2].v[component];
+  const h = (j2) => k[j2 + 1].t - k[j2].t;
+  const d = (j2) => (v(j2 + 1) - v(j2)) / h(j2);
+  const harmonic = (a, b, h0, h1) => a * b <= 0 ? 0 : 3 * (h0 + h1) / ((2 * h1 + h0) / a + (h1 + 2 * h0) / b);
+  const tangent = (j2) => {
+    if (j2 === 0 || j2 === n - 1) {
+      if (loop && n > 2 && v(0) === v(n - 1) && k[0].ease !== "step" && k[n - 2].ease !== "step")
+        return harmonic(d(n - 2), d(0), h(n - 2), h(0));
+      return 0;
+    }
+    if (k[j2 - 1].ease === "step" || k[j2].ease === "step") return 0;
+    return harmonic(d(j2 - 1), d(j2), h(j2 - 1), h(j2));
+  };
+  const u = (t - k[i].t) / h(i), u2 = u * u, u3 = u2 * u;
+  return (2 * u3 - 3 * u2 + 1) * v(i) + (u3 - 2 * u2 + u) * h(i) * tangent(i) + (-2 * u3 + 3 * u2) * v(i + 1) + (u3 - u2) * h(i) * tangent(i + 1);
+}
+function sample(track, t, loop = false) {
   const keys = track.keys;
   if (t <= keys[0].t) return keys[0].v;
   const last = keys[keys.length - 1];
@@ -583,22 +734,44 @@ function sample(track, t) {
   let i = 0;
   while (keys[i + 1].t <= t) i++;
   const a = keys[i], b = keys[i + 1];
+  if (a.ease === "step") return a.v;
   if (typeof a.v === "number" && typeof b.v === "number") {
+    if (track.interpolation === "pchip") return smoothValue(track, i, t, void 0, loop);
     const u = ease(a.ease)((t - a.t) / (b.t - a.t));
     return a.v + (b.v - a.v) * u;
   }
   if (Array.isArray(a.v) && Array.isArray(b.v) && typeof a.v[0] === "number") {
+    if (track.interpolation === "pchip") return a.v.map((_, j2) => smoothValue(track, i, t, j2, loop));
     const u = ease(a.ease)((t - a.t) / (b.t - a.t)), av = a.v, bv = b.v;
     return av.map((v, k) => v + ((bv[k] ?? v) - v) * u);
   }
   return a.v;
 }
 function poseOf(anim, t, out = /* @__PURE__ */ new Map()) {
-  for (const tr of anim.tracks) out.set(pk(tr.target, tr.id, tr.prop), sample(tr, t));
+  for (const tr of anim.tracks) out.set(pk(tr.target, tr.id, tr.prop), sample(tr, t, anim.loop && tr.keys[0].t === 0 && tr.keys.at(-1).t === anim.duration));
+  return out;
+}
+function blendPoses(from, to, w, restOf) {
+  if (w >= 1) return new Map(to);
+  const out = /* @__PURE__ */ new Map();
+  for (const k of /* @__PURE__ */ new Set([...from.keys(), ...to.keys()])) {
+    const f = from.has(k) ? from.get(k) : restOf(k);
+    const cur = to.has(k) ? to.get(k) : restOf(k);
+    if (typeof f === "number" && !Array.isArray(cur)) {
+      const target = typeof cur === "number" ? cur : restOf(k);
+      out.set(k, f + (target - f) * w);
+    } else if (Array.isArray(f) && typeof f[0] === "number") {
+      const fv = f, tv = Array.isArray(cur) && typeof cur[0] === "number" ? cur : fv.map(() => 0);
+      out.set(k, fv.map((v, i) => v + ((tv[i] ?? 0) - v) * w));
+    } else if (Array.isArray(cur) && typeof cur[0] === "number" && typeof f !== "string") {
+      out.set(k, cur.map((v) => v * w));
+    } else out.set(k, f ?? null);
+  }
   return out;
 }
 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 s2 = doc.slots.find((s3) => s3.id === id);
@@ -705,7 +878,9 @@ function updateSubtree(skel, root3) {
     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 s2 = localOf(doc, pose, b);
@@ -766,10 +941,43 @@ function aimAt(skel, boneId, tx, ty, mix, compress = false, stretch = false, uni
   updateSubtree(skel, boneId);
 }
 var shortest = (deg) => ((deg + 180) % 360 + 360) % 360 - 180;
+function applyLongIk(skel, c, tx, ty, mix) {
+  const initial = c.bones.map((id) => ({ ...skel.bones.get(id) }));
+  const last = c.bones.at(-1), len = boneOf(skel.doc, last).length;
+  const end = () => apply(skel.bones.get(last).world, len, 0);
+  const tolerance = c.tolerance ?? 0.05;
+  const root3 = skel.bones.get(c.bones[0]).world, tip = end();
+  if (Math.abs((tip[0] - root3.tx) * (ty - root3.ty) - (tip[1] - root3.ty) * (tx - root3.tx)) < 1e-7 && Math.hypot(tx - root3.tx, ty - root3.ty) < Math.hypot(tip[0] - root3.tx, tip[1] - root3.ty) - tolerance) {
+    skel.bones.get(last).rotation += cnum(skel, "ik", c.id, "bendPositive", c.bendPositive) > 0.5 ? 5 : -5;
+    updateSubtree(skel, last);
+  }
+  for (let iter = 0; iter < (c.iterations ?? 100); iter++) {
+    const e = end();
+    if (Math.hypot(e[0] - tx, e[1] - ty) <= tolerance) break;
+    for (let i = c.bones.length - 1; i >= 0; i--) {
+      const id = c.bones[i], b = boneOf(skel.doc, id), st = skel.bones.get(id), w = st.world, e2 = end();
+      const angle = wrapRad(Math.atan2(ty - w.ty, tx - w.tx) - Math.atan2(e2[1] - w.ty, e2[0] - w.tx));
+      const cos = Math.cos(angle), sin = Math.sin(angle);
+      setEffectiveWorld(skel, b, st, { ...w, a: cos * w.a - sin * w.b, b: sin * w.a + cos * w.b, c: cos * w.c - sin * w.d, d: sin * w.c + cos * w.d });
+    }
+  }
+  if (mix < 1) {
+    c.bones.forEach((id, i) => {
+      const st = skel.bones.get(id), from = initial[i];
+      for (const p of ["rotation", "shearX", "shearY"]) st[p] = from[p] + shortest(st[p] - from[p]) * mix;
+      for (const p of ["x", "y", "scaleX", "scaleY"]) st[p] = from[p] + (st[p] - from[p]) * mix;
+    });
+    updateSubtree(skel, c.bones[0]);
+  }
+}
 function applyIk(skel, c) {
   const mix = cnum(skel, "ik", c.id, "mix", c.mix);
   if (mix <= 0) return;
   const target = skel.bones.get(c.target).world;
+  if (c.bones.length > 2) {
+    applyLongIk(skel, c, target.tx, target.ty, mix);
+    return;
+  }
   const bendDir = cnum(skel, "ik", c.id, "bendPositive", c.bendPositive) > 0.5 ? 1 : -1;
   const compress = cnum(skel, "ik", c.id, "compress", c.compress) > 0.5, stretch = cnum(skel, "ik", c.id, "stretch", c.stretch) > 0.5;
   let softness = cnum(skel, "ik", c.id, "softness", c.softness);
@@ -904,6 +1112,7 @@ function applyTransformConstraint(skel, c) {
   const mixRotate = cnum(skel, "transform", c.id, "mixRotate", c.mixRotate), mixX = cnum(skel, "transform", c.id, "mixX", c.mixX), mixY = cnum(skel, "transform", c.id, "mixY", c.mixY);
   const mixScaleX = cnum(skel, "transform", c.id, "mixScaleX", c.mixScaleX), mixScaleY = cnum(skel, "transform", c.id, "mixScaleY", c.mixScaleY), mixShearY = cnum(skel, "transform", c.id, "mixShearY", c.mixShearY);
   if (!mixRotate && !mixX && !mixY && !mixScaleX && !mixScaleY && !mixShearY) return;
+  c = { ...c, ...Object.fromEntries(["x", "y", "rotation", "scaleX", "scaleY", "shearY"].map((p) => [p, cnum(skel, "transform", c.id, p, c[p])])) };
   const target = skel.bones.get(c.target), tw = target.world;
   const offsetRotation = c.rotation * DEG2, offsetShearY = c.shearY * DEG2;
   for (const id of c.bones) {
@@ -1294,10 +1503,10 @@ function traceLoops(mask, threshold) {
   return loops;
 }
 function traceHulls(mask, opts = {}) {
-  const { threshold = 8, tolerance = 2, margin = 1 } = opts;
+  const { threshold = 8, tolerance = 2, margin = 1, minIslandRatio = MIN_ISLAND_AREA } = opts;
   const loops = traceLoops(mask, threshold).map((l) => ({ l, a: signedArea(l) }));
   const biggest = loops.reduce((m, x) => Math.abs(x.a) > Math.abs(m.a) ? x : m, loops[0]);
-  const islands = loops.filter((x) => Math.sign(x.a) === Math.sign(biggest.a) && Math.abs(x.a) >= MIN_ISLAND_AREA * Math.abs(biggest.a)).sort((p, q) => Math.abs(q.a) - Math.abs(p.a));
+  const islands = loops.filter((x) => Math.sign(x.a) === Math.sign(biggest.a) && Math.abs(x.a) >= minIslandRatio * Math.abs(biggest.a)).sort((p, q) => Math.abs(q.a) - Math.abs(p.a));
   return islands.map(({ l }) => {
     const s2 = simplify(dropCollinear(l), tolerance);
     return margin ? offsetPolygon(s2, margin) : s2;
@@ -1700,6 +1909,54 @@ function pathFromPoints(skel, slotId, points, closed) {
   }
   return { vertices, closed, lengths: curveLengths(flatten(ctrl.flat()), closed) };
 }
+function constraintDependencies(doc) {
+  const parent = new Map(doc.bones.map((b) => [b.id, b.parent]));
+  const ancestors = (id) => {
+    const out = /* @__PURE__ */ new Set();
+    for (let b = id; b && !out.has(b); b = parent.get(b)) out.add(b);
+    return out;
+  };
+  const all = [
+    ...doc.ik.map((c) => ({ kind: "ik", ...c })),
+    ...doc.transform.map((c) => ({ kind: "transform", ...c })),
+    ...doc.path.map((c) => ({ kind: "path", ...c }))
+  ].sort((a, b) => a.order - b.order);
+  const active2 = (c) => MIX_PROPS[c.kind].some((p) => c[p] !== 0 || doc.animations.some((a) => a.tracks.some((t) => t.target === c.kind && t.id === c.id && t.prop === p && t.keys.some((k) => typeof k.v === "number" && k.v !== 0))));
+  const edges = [];
+  all.forEach((reader, ri) => {
+    if (!active2(reader)) return;
+    const reads = /* @__PURE__ */ new Set();
+    const add = (b) => ancestors(b).forEach((x) => reads.add(x));
+    if (reader.kind === "path") {
+      const slot = doc.slots.find((s2) => s2.id === reader.target);
+      if (slot) add(slot.bone);
+      for (const a of doc.attachments) if (a.slot === reader.target && a.type === "path") {
+        for (const list of a.weights ?? []) for (const inf of list) if (inf.w !== 0) add(inf.bone);
+      }
+    } else add(reader.target);
+    for (const b of reader.bones) {
+      const p = parent.get(b);
+      if (p && !reader.bones.includes(p)) add(p);
+    }
+    all.forEach((writer, wi) => {
+      if (ri === wi || !active2(writer)) return;
+      const bone = writer.bones.find((b) => reads.has(b));
+      if (bone) edges.push({ reader: reader.id, readerKind: reader.kind, writer: writer.id, writerKind: writer.kind, bone, late: wi > ri });
+    });
+  });
+  return { all, edges };
+}
+function orderConstraints(doc) {
+  const { all, edges } = constraintDependencies(doc);
+  const pending3 = [...all], ids = [];
+  while (pending3.length) {
+    const i = pending3.findIndex((c2) => edges.filter((e) => e.reader === c2.id && e.readerKind === c2.kind).every((e) => ids.includes(`${e.writerKind}:${e.writer}`)));
+    if (i < 0) throw new Error(`constraint dependency cycle: ${pending3.map((c2) => c2.id).join(", ")}`);
+    const c = pending3.splice(i, 1)[0];
+    ids.push(`${c.kind}:${c.id}`);
+  }
+  return { ...doc, ik: doc.ik.map((c) => ({ ...c, order: ids.indexOf(`ik:${c.id}`) })), transform: doc.transform.map((c) => ({ ...c, order: ids.indexOf(`transform:${c.id}`) })), path: doc.path.map((c) => ({ ...c, order: ids.indexOf(`path:${c.id}`) })) };
+}
 
 // src/rig-tools.ts
 function createDoc(name, width, height, notes) {
@@ -1801,13 +2058,13 @@ function placeAsset(doc, p) {
   const boneId = cur?.bone ?? p.bone;
   const world = evaluate(doc, /* @__PURE__ */ new Map()).bones.get(boneId)?.world;
   if (!world) throw new Error(`unknown bone "${boneId}"`);
-  const z3 = p.z ?? cur?.z ?? (doc.slots.length ? Math.max(...doc.slots.map((s2) => s2.z)) + 1 : 0);
-  let next = cur ? doc : setSlot(doc, { id: slotId, bone: boneId, z: z3 });
+  const z4 = p.z ?? cur?.z ?? (doc.slots.length ? Math.max(...doc.slots.map((s2) => s2.z)) + 1 : 0);
+  let next = cur ? doc : setSlot(doc, { id: slotId, bone: boneId, z: z4 });
   const [lx, ly] = apply(invert(world), p.x, p.y);
   next = setAttachment(next, { id: p.asset, slot: slotId, asset: p.asset, x: round4(lx), y: round4(ly) });
   return setSlot(next, { id: slotId, attachment: p.asset, ...p.z !== void 0 ? { z: p.z } : {} });
 }
-function layerPrompt(doc, assetId) {
+function layerPrompt(doc, assetId, opts = {}) {
   const a = doc.assets.find((a2) => a2.id === assetId);
   if (!a) throw new Error(`unknown asset "${assetId}"`);
   const att = doc.attachments.find((a2) => a2.type !== "path" && a2.asset === assetId);
@@ -1820,10 +2077,15 @@ function layerPrompt(doc, assetId) {
     `Part: ${a.origin?.prompt ?? a.id}.`,
     `Size: ${a.width}\xD7${a.height} px at source scale${a.origin?.bbox ? ` (source bbox [${a.origin.bbox.join(", ")}])` : ""}; keep the same silhouette registration` + (att && att.type === "region" ? ` so the image centre stays at (${+att.x.toFixed(1)}, ${+att.y.toFixed(1)}) from the joint.` : "."),
     bone ? `Rig context: attached to bone "${bone.id}"${bone.parent ? `, parent "${bone.parent}"` : ""}${children.length ? `; child parts: ${children.join(", ")}` : ""}.` : "Rig context: not attached yet.",
-    "Add about 20 px (source scale) of overlap beyond every joint end so rotation cannot expose a cut.",
+    "Paint overlap beyond each hidden joint end through the planned motion range; choose its depth from the pivot and extreme poses, not a fixed pixel margin.",
     "Composition: orthographic front view, one connected opaque part only, same orientation as the current layer, centred with generous padding, no foreshortening.",
-    "Backdrop: perfectly flat uniform #00FF00 chroma-key background with no gradient, floor, shadow, text or watermark; do not use #00FF00 inside the part."
+    "Backdrop: transparent RGBA, no floor, shadow, text or watermark. If the selected generator cannot output alpha, use a flat #00FF00 guide background and remove only the reviewed background region."
   ];
+  if (opts.method === "repair") lines.push(
+    "Complete the host part inside the marked hidden-surface region. Retain surrounding art as a registration guide; small differences outside the repair are acceptable because assembly keeps the approved pixels there.",
+    `Do not recreate removed occluders${opts.removed?.length ? ": " + opts.removed.join(", ") : " (neighbouring parts deliberately removed from the guide)"}. Continue only this part's own material and contour; no guide magenta in the output.`,
+    "After generation: fit unchanged landmarks, remove explicitly masked background, match host-material tone, feather into the host colour and repair pale fringe only inside the ink mask."
+  );
   return lines.join("\n");
 }
 function setMeta(doc, patch) {
@@ -1844,6 +2106,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,
@@ -1876,6 +2141,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((s2) => s2.id === slot.id);
   if (cur && slot.bone && slot.bone !== cur.bone) doc = rebindSlot(doc, slot.id, slot.bone).doc;
   const base = doc.slots.find((s2) => s2.id === slot.id);
@@ -1887,7 +2157,7 @@ function removeSlot(doc, id) {
   const gone = new Set(doc.attachments.filter((a) => a.slot === id).map((a) => a.id));
   return patchDrawOrder({
     ...doc,
-    slots: doc.slots.filter((s2) => s2.id !== id),
+    slots: doc.slots.filter((s2) => s2.id !== id).map((s2) => gone.has(s2.clip ?? "") ? { ...s2, clip: void 0 } : s2),
     attachments: doc.attachments.filter((a) => a.slot !== id),
     animations: doc.animations.map((a) => ({ ...a, tracks: a.tracks.filter((t) => !(t.target === "slot" && t.id === id || t.target === "deform" && gone.has(t.id))) }))
   }, (o) => o.filter((s2) => s2 !== id));
@@ -1935,8 +2205,8 @@ function rebindSlot(doc, slotId, bone) {
 function setDrawOrder(doc, order) {
   const ids = new Set(doc.slots.map((s2) => s2.id));
   if (order.length !== ids.size || new Set(order).size !== order.length || !order.every((s2) => ids.has(s2))) throw new Error("order must list every slot exactly once");
-  const z3 = new Map(order.map((id, i) => [id, i]));
-  return { ...doc, slots: doc.slots.map((s2) => ({ ...s2, z: z3.get(s2.id) })) };
+  const z4 = new Map(order.map((id, i) => [id, i]));
+  return { ...doc, slots: doc.slots.map((s2) => ({ ...s2, z: z4.get(s2.id) })) };
 }
 function setAttachment(doc, att) {
   const cur = doc.attachments.find((a) => a.id === att.id);
@@ -1974,31 +2244,33 @@ function setMesh(doc, id, patch) {
   const len = deformLength(next);
   return dropVertexKeys(withAtt, id, (l) => l === len);
 }
-var setWeights = (doc, id, weights) => setMesh(doc, id, { weights });
-function convertToMesh(doc, mesh) {
-  const cur = doc.attachments.find((a) => a.id === mesh.id);
-  if (!cur || cur.type !== "region") throw new Error(`attachment "${mesh.id}" is not a region`);
+var setWeights = (doc, id, weights) => {
+  const old = doc.attachments.find((a) => a.id === id);
+  const sameLayout = old?.type === "mesh" && old.weights?.length === weights.length && old.weights.every((list, i) => list.length === weights[i].length && list.every((inf, j2) => inf.bone === weights[i][j2].bone));
+  const result = setMesh(doc, id, { weights });
+  if (sameLayout) return result;
+  const cleared = dropVertexKeys(result.doc, id, () => false);
+  return { doc: cleared.doc, dropped: [...result.dropped, ...cleared.dropped] };
+};
+function convertToMesh(doc, mesh2) {
+  const cur = doc.attachments.find((a) => a.id === mesh2.id);
+  if (!cur || cur.type !== "region") throw new Error(`attachment "${mesh2.id}" is not a region`);
   const droppedTracks = [];
   const animations = doc.animations.map((a) => ({ ...a, tracks: a.tracks.filter((t) => {
-    const drop = t.target === "deform" && t.id === mesh.id;
+    const drop = t.target === "deform" && t.id === mesh2.id;
     if (drop) droppedTracks.push(`${trackId2(t)} in ${a.id}`);
     return !drop;
   }) }));
-  return { doc: { ...doc, attachments: doc.attachments.map((a) => a.id === mesh.id ? Attachment.parse(mesh) : a), animations }, droppedTracks };
+  return { doc: { ...doc, attachments: doc.attachments.map((a) => a.id === mesh2.id ? Attachment.parse(mesh2) : a), animations }, droppedTracks };
 }
 function removeAttachment(doc, id) {
   return {
     ...doc,
     attachments: doc.attachments.filter((a) => a.id !== id),
-    slots: doc.slots.map((s2) => s2.attachment === id ? { ...s2, attachment: void 0 } : s2),
+    slots: doc.slots.map((s2) => ({ ...s2, attachment: s2.attachment === id ? void 0 : s2.attachment, clip: s2.clip === id ? void 0 : s2.clip })),
     animations: doc.animations.map((a) => ({ ...a, tracks: a.tracks.filter((t) => !(t.target === "deform" && t.id === id)).map((t) => t.target === "slot" && t.prop === "attachment" ? { ...t, keys: t.keys.map((k) => k.v === id ? { ...k, v: null } : k) } : t) }))
   };
 }
-function placementFromPivot(pivot, offset, w, h) {
-  const o = { x: 0, y: 0, rotation: 0, scaleX: 1, scaleY: 1, ...offset };
-  const [x, y] = apply(affineOf(o.x, o.y, o.rotation, o.scaleX, o.scaleY), (0.5 - pivot.x) * w, (0.5 - pivot.y) * h);
-  return { x: +x.toFixed(4) + 0, y: +y.toFixed(4) + 0, rotation: o.rotation, scaleX: o.scaleX, scaleY: o.scaleY };
-}
 var CONSTRAINT_SCHEMA = { ik: IkConstraint, transform: TransformConstraint, path: PathConstraint };
 var article = (kind) => kind === "ik" ? "an" : "a";
 var constraintKind = (doc, id) => doc.ik.some((c) => c.id === id) ? "ik" : doc.transform.some((c) => c.id === id) ? "transform" : doc.path.some((c) => c.id === id) ? "path" : void 0;
@@ -2010,8 +2282,10 @@ function setConstraint(doc, kind, id, patch) {
   const given = Object.fromEntries(Object.entries(patch).filter(([, v]) => v !== void 0));
   if (!cur && !(given.bones && given.target)) throw new Error(`no ${kind} constraint "${id}" yet: creating one needs at least bones and target`);
   const next = CONSTRAINT_SCHEMA[kind].parse({ ...cur, ...given, id });
-  if (kind === "ik" && next.bones.length > 2) throw new Error(`ik "${id}": 1 or 2 bones, got ${next.bones.length} (${next.bones.join(",")})`);
   const list = cur ? doc[kind].map((c) => c.id === id ? next : c) : [...doc[kind], next];
+  if (kind === "ik") {
+    for (let i = 1; i < next.bones.length; i++) if (doc.bones.find((b) => b.id === next.bones[i])?.parent !== next.bones[i - 1]) throw new Error(`ik "${id}": bones must form a contiguous parent-to-child chain`);
+  }
   return { ...doc, [kind]: list };
 }
 function removeConstraint(doc, id) {
@@ -2026,8 +2300,10 @@ function removeConstraint(doc, id) {
 function addIkChain(doc, bone, opts = {}) {
   const id = `${bone}_ik`;
   if (constraintKind(doc, id)) throw new Error(`constraint "${id}" exists; remove it first (rig_remove_constraint) or patch it`);
-  const full = ikChainFor(doc, bone);
+  const full = opts.bones ?? ikChainFor(doc, bone);
+  if (!full.length || full.at(-1) !== bone) throw new Error("explicit chain must end at the named tip bone");
   const rootId = doc.bones.find((b) => !b.parent).id;
+  if (opts.bones && full.includes(rootId)) throw new Error("explicit chain cannot include the root carrying its target");
   const note = full.includes(rootId) ? "single bone \u2014 the two-bone chain would include the root, which carries the target" : void 0;
   const chain = note ? [bone] : full;
   if (chain.length === 1 && !doc.bones.find((b) => b.id === bone).length)
@@ -2141,10 +2417,11 @@ function pathAnchorOp(doc, id, op, index, t = 0.5) {
 function setKeys(doc, animId, track, keys, duration, opts = {}) {
   const anim = doc.animations.find((a) => a.id === animId) ?? { id: animId, duration: duration ?? 1, loop: false, tracks: [], events: [] };
   const same = (t) => t.target === track.target && t.id === track.id && t.prop === track.prop;
+  const old = anim.tracks.find(same);
   const given = keys.map((k) => ({ ...k, ease: k.ease ?? "ease_in_out" }));
   const kept = opts.merge ? (anim.tracks.find(same)?.keys ?? []).filter((k) => !given.some((g) => Math.abs(g.t - k.t) < 1e-9)) : [];
   const sorted = [...kept, ...given].sort((a, b) => a.t - b.t);
-  const edited = { ...track, keys: sorted };
+  const edited = { ...old, ...track, interpolation: track.interpolation ?? old?.interpolation, keys: sorted };
   const tracks = anim.tracks.some(same) ? anim.tracks.map((t) => same(t) ? edited : t) : [...anim.tracks, edited];
   const dur = duration ?? Math.max(anim.duration, ...sorted.map((k) => k.t));
   const next = { ...anim, tracks, duration: dur, preset: void 0 };
@@ -2227,7 +2504,7 @@ function copyTracks(doc, animId, from, to, opts) {
         const shifted = round6(k.t + shift);
         return { t: shifted >= anim.duration ? shifted - anim.duration : shifted, v: mirror ? -k.v : k.v, ease: k.ease };
       });
-      next = setKeys(next, animId, { target: "bone", id: dstId, prop: t.prop }, keys);
+      next = setKeys(next, animId, { target: "bone", id: dstId, prop: t.prop, interpolation: t.interpolation }, keys);
       copied++;
     }
     if (!any) empty.push(srcId);
@@ -2243,6 +2520,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;
@@ -2287,7 +2565,7 @@ function rename2(doc, kind, id, to) {
       return {
         ...doc,
         attachments: doc.attachments.map((a) => ({ ...a, id: sub(a.id) })),
-        slots: doc.slots.map((s2) => s2.attachment ? { ...s2, attachment: sub(s2.attachment) } : s2)
+        slots: doc.slots.map((s2) => ({ ...s2, attachment: s2.attachment ? sub(s2.attachment) : void 0, clip: s2.clip ? sub(s2.clip) : void 0 }))
       };
     }
     case "asset": {
@@ -2317,13 +2595,15 @@ function describeAttachment(doc, att) {
   }
   const n = vertexCount(att);
   const bones = att.weights ? [...new Set(att.weights.flat().map((i) => i.bone))] : [];
-  const skin = att.weights ? `skinned to ${bones.length} bone${bones.length === 1 ? "" : "s"} (${bones.join(", ")}), ${att.weights.reduce((t, l) => t + l.length, 0)} influences` : `unskinned (\`vertices\` in slot bone "${doc.slots.find((s2) => s2.id === att.slot)?.bone ?? "?"}"'s space)`;
+  const skin2 = att.weights ? `skinned to ${bones.length} bone${bones.length === 1 ? "" : "s"} (${bones.join(", ")}), ${att.weights.reduce((t, l) => t + l.length, 0)} influences` : `unskinned (\`vertices\` in slot bone "${doc.slots.find((s2) => s2.id === att.slot)?.bone ?? "?"}"'s space)`;
   const shape = att.type === "mesh" ? `${n} vertices, ${att.triangles.length / 3} triangles, hull ${att.hull}` : `${n} control points = ${anchorCount(n)} anchors, ${att.closed ? "closed" : "open"}, ${att.constantSpeed ? "constantSpeed" : "stored lengths"}`;
   const keyed = doc.animations.filter((a) => a.tracks.some((t) => t.target === "deform" && t.id === att.id && t.prop === "vertices")).map((a) => a.id);
-  return `${head}: ${shape}; ${skin}; deform key length ${deformLength(att)}${keyed.length ? `; vertices keyed in ${keyed.length} animation${keyed.length === 1 ? "" : "s"} (${keyed.join(", ")})` : ""}`;
+  return `${head}: ${shape}; ${skin2}; deform key length ${deformLength(att)}${keyed.length ? `; vertices keyed in ${keyed.length} animation${keyed.length === 1 ? "" : "s"} (${keyed.join(", ")})` : ""}`;
 }
 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 = (s2) => {
@@ -2481,9 +2761,11 @@ async function importLayers(doc, dir, relPrefix = "layers") {
   let specs;
   try {
     specs = JSON.parse(await readFile(join2(dir, "layers.json"), "utf8"));
-  } catch {
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
     specs = (await readdir(dir)).filter((f) => f.endsWith(".png")).sort().map((file) => ({ file }));
   }
+  if (!Array.isArray(specs)) throw new Error("layers.json must be an array");
   let next = doc;
   const parsed = [];
   for (const s2 of specs) {
@@ -2491,21 +2773,32 @@ async function importLayers(doc, dir, relPrefix = "layers") {
     const [w, h] = pngSize(buf);
     const m = basename2(s2.file, ".png").match(/^(?:(\d+)_)?(.+)$/);
     const id = s2.id ?? m[2].toLowerCase().replace(/[^a-z0-9_]/g, "_");
-    const z3 = s2.z ?? (m[1] ? +m[1] : parsed.length);
+    const z4 = s2.z ?? (m[1] ? +m[1] : parsed.length);
     const role = s2.role ?? (DEFAULT_PARENT[id] || id === "root" ? id : void 0);
     const bbox = s2.bbox ?? [0, 0, w, h];
-    parsed.push({ ...s2, id, z: z3, role, w, h, bbox });
+    if (bbox.length !== 4 || bbox.some((v) => !Number.isFinite(v)) || bbox[2] <= 0 || bbox[3] <= 0)
+      throw new Error(`layer "${id}": bbox must have positive width and height`);
+    parsed.push({ ...s2, id, z: z4, role, w, h, bbox });
   }
   const ids = new Set(parsed.map((p) => p.id));
   const rootId = next.bones.find((b) => !b.parent).id;
   const exists3 = (id) => ids.has(id) || next.bones.some((b) => b.id === id);
   const resolveParent = (p) => {
-    if (p.parent && exists3(p.parent)) return p.parent;
+    if (p.parent) {
+      if (!exists3(p.parent)) throw new Error(`layer "${p.id}": unknown parent "${p.parent}"`);
+      return p.parent;
+    }
     let cur = p.role && DEFAULT_PARENT[p.role];
     while (cur && !exists3(cur)) cur = DEFAULT_PARENT[cur];
     return cur ?? rootId;
   };
-  const dependency = (p) => p.bone && exists3(p.bone) ? p.bone : resolveParent(p);
+  const dependency = (p) => {
+    if (p.bone) {
+      if (!exists3(p.bone)) throw new Error(`layer "${p.id}": unknown bone "${p.bone}"`);
+      return p.bone;
+    }
+    return resolveParent(p);
+  };
   const pending3 = [...parsed];
   while (pending3.length) {
     const i = pending3.findIndex((p2) => next.bones.some((b) => b.id === dependency(p2)));
@@ -2514,36 +2807,45 @@ async function importLayers(doc, dir, relPrefix = "layers") {
     if (!next.bones.some((b) => b.id === target)) throw new Error(`layer "${p.id}": bone "${target}" is neither in the rig nor in the import`);
     const [bx, by, bw, bh] = p.bbox;
     const joint = p.joint ?? [bx + bw / 2, by + bh / 2];
-    const host = worldOf(next, target);
+    const host = evaluate(next, /* @__PURE__ */ new Map()).bones.get(target).world;
+    if (Math.abs(host.a * host.d - host.b * host.c) < 1e-10) throw new Error(`layer "${p.id}": singular host transform`);
     next = { ...next, assets: [...next.assets, RigSchema.shape.assets.element.parse({
       id: p.id,
       src: `${relPrefix}/${p.file}`,
       width: p.w,
       height: p.h,
-      origin: { sourceImage: p.sourceImage, bbox: s_bbox(p), inpainted: p.inpainted ?? false, prompt: p.prompt }
+      origin: { bboxSpace: "document", sourceImage: p.sourceImage, bbox: s_bbox(p), inpainted: p.inpainted ?? false, prompt: p.prompt }
     })] };
-    const pivot = { x: (joint[0] - bx) / bw, y: (joint[1] - by) / bh };
+    const place = (slotId) => {
+      const slot = next.slots.find((s2) => s2.id === slotId);
+      const inv = invert(evaluate(next, /* @__PURE__ */ new Map()).bones.get(slot.bone).world);
+      const [x, y] = apply(inv, bx + bw / 2, by + bh / 2);
+      const m = { a: inv.a * bw / p.w, b: inv.b * bw / p.w, c: inv.c * bh / p.h, d: inv.d * bh / p.h, tx: x, ty: y };
+      const sx = Math.hypot(m.a, m.b), sy = Math.hypot(m.c, m.d);
+      if (Math.abs(m.a * m.c + m.b * m.d) > 1e-8 * sx * sy) {
+        const vertices = [[bx, by], [bx + bw, by], [bx + bw, by + bh], [bx, by + bh]].flatMap(([x2, y2]) => apply(inv, x2, y2));
+        const att = Attachment.parse({ id: p.id, slot: slotId, type: "mesh", asset: p.id, vertices, uvs: [0, 0, 1, 0, 1, 1, 0, 1], triangles: [0, 1, 2, 0, 2, 3], hull: 4 });
+        next = { ...next, attachments: [...next.attachments.filter((a) => a.id !== p.id), att] };
+      } else next = setAttachment(next, { id: p.id, slot: slotId, asset: p.id, x: +x.toFixed(12), y: +y.toFixed(12), rotation: Math.atan2(m.b, m.a) * 180 / Math.PI, scaleX: sx, scaleY: (m.a * m.d - m.b * m.c < 0 ? -1 : 1) * sy });
+    };
     if (p.swap || p.bone) {
       const slotId = p.slot ?? p.id;
       if (!next.slots.some((s2) => s2.id === slotId)) next = setSlot(next, { id: slotId, bone: target, z: p.z, blend: p.blend });
-      next = setAttachment(next, { id: p.id, slot: slotId, asset: p.id, ...placementFromPivot(pivot, { x: joint[0] - host.x, y: joint[1] - host.y }, p.w, p.h) });
+      place(slotId);
       if (!p.swap) next = setSlot(next, { id: slotId, attachment: p.id });
       continue;
     }
-    if (!next.bones.some((b) => b.id === p.id))
-      next = addBone(next, { id: p.id, parent: target, role: p.role, transform: { x: joint[0] - host.x, y: joint[1] - host.y, rotation: 0, scaleX: 1, scaleY: 1 } });
+    if (!next.bones.some((b) => b.id === p.id)) {
+      const [x, y] = apply(invert(host), ...joint);
+      next = addBone(next, { id: p.id, parent: target, role: p.role, transform: { x, y } });
+    }
     next = setSlot(next, { id: p.id, bone: p.id, z: p.z, blend: p.blend });
-    next = setAttachment(next, { id: p.id, slot: p.id, asset: p.id, ...placementFromPivot(pivot, {}, p.w, p.h) });
+    place(p.id);
     next = setSlot(next, { id: p.id, attachment: p.id });
   }
   return next;
 }
 var s_bbox = (p) => p.bbox;
-function worldOf(doc, id) {
-  const b = doc.bones.find((b2) => b2.id === id);
-  const p = b.parent ? worldOf(doc, b.parent) : { x: 0, y: 0 };
-  return { x: p.x + b.transform.x, y: p.y + b.transform.y };
-}
 
 // src/rig-presets.ts
 var root = (doc) => doc.bones.find((b) => !b.parent);
@@ -2751,18 +3053,57 @@ function applyPreset(doc, name, params = {}) {
   return { ...doc, animations };
 }
 
+// src/preview/export-video.ts
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { mkdtemp, writeFile as writeFile2, rm as rm2, rename as rename3, mkdir as mkdir2 } from "node:fs/promises";
+import { dirname as dirname4, join as join5 } from "node:path";
+
 // src/preview/render-preview.ts
 import { chromium } from "playwright";
-import { readFile as readFile2 } from "node:fs/promises";
-import { join as join3, dirname as dirname2 } from "node:path";
+import { readFile as readFile3 } from "node:fs/promises";
+import { join as join4, dirname as dirname3 } from "node:path";
 import { fileURLToPath } from "node:url";
-var HERE = dirname2(fileURLToPath(import.meta.url));
+
+// src/rig-qa.ts
+import { createHash } from "node:crypto";
+import { readFile as readFile2, readdir as readdir2 } from "node:fs/promises";
+import { dirname as dirname2, join as join3 } from "node:path";
+var sha256 = (data) => createHash("sha256").update(data).digest("hex");
+async function verifyRenderManifest(rigPath, framesDir, expected) {
+  const m = JSON.parse(await readFile2(join3(framesDir, "manifest.json"), "utf8"));
+  if (m.version !== 1 || !m.frames?.length || !m.times?.length) throw new Error("missing or empty capture manifest");
+  const raw = await readFile2(rigPath, "utf8");
+  if (sha256(raw) !== m.rigFile) throw new Error("stale render: rig file changed");
+  const doc = parse(JSON.parse(raw));
+  if (sha256(JSON.stringify(doc)) !== m.identity.document) throw new Error("stale render: rig changed");
+  if (sha256(await readFile2(expected.renderer)) !== m.identity.renderer) throw new Error("stale render: renderer changed");
+  for (const a of doc.assets) if (sha256(await readFile2(join3(dirname2(rigPath), a.src))) !== m.identity.assets[a.src]) throw new Error(`stale render: texture ${a.src} changed`);
+  for (const [path, hash] of Object.entries(m.identity.masks)) if (sha256(await readFile2(join3(dirname2(rigPath), path))) !== hash) throw new Error(`stale render: fill mask ${path} changed`);
+  if (m.animation !== (expected.animation ?? null) || JSON.stringify(m.times) !== JSON.stringify(expected.times)) throw new Error("capture does not cover the requested animation/times");
+  if (expected.transparent !== void 0 && m.transparent !== expected.transparent) throw new Error("capture has the wrong alpha mode");
+  if (m.frames.length !== expected.times.length || new Set(m.frames.map((f) => f.file)).size !== m.frames.length) throw new Error("capture has missing or duplicate frames");
+  const files2 = (await readdir2(framesDir)).filter((f) => f.endsWith(".png")).sort();
+  if (JSON.stringify(files2) !== JSON.stringify(m.frames.map((f) => f.file).sort())) throw new Error("capture directory has missing or unmanifested frames");
+  for (const f of m.frames) {
+    if (!/^\d{6}\.png$/.test(f.file)) throw new Error("invalid capture filename");
+    if (sha256(await readFile2(join3(framesDir, f.file))) !== f.sha256) throw new Error(`frame ${f.file} changed since capture`);
+  }
+  return m;
+}
+
+// src/preview/render-preview.ts
+import { PNG } from "pngjs";
+var HERE = dirname3(fileURLToPath(import.meta.url));
 var browser;
 var page;
 var harnessJs;
 var pending2 = Promise.resolve();
 async function getPage() {
-  if (page && !page.isClosed()) return page;
+  const latestHarness = await readFile3(join4(HERE, "harness.js"), "utf8");
+  if (page && !page.isClosed() && latestHarness === harnessJs) return page;
+  if (page && !page.isClosed()) await page.close();
+  harnessJs = latestHarness;
   if (browser && !browser.isConnected()) browser = void 0;
   browser ??= await chromium.launch({
     headless: true,
@@ -2772,7 +3113,7 @@ async function getPage() {
   try {
     next.on("pageerror", (e) => console.error("[harness]", e.message));
     await next.setContent(`<!doctype html><html><body style="margin:0;background:transparent"></body></html>`);
-    harnessJs ??= await readFile2(join3(HERE, "harness.js"), "utf8");
+    harnessJs ??= await readFile3(join4(HERE, "harness.js"), "utf8");
     await next.addScriptTag({ content: harnessJs });
     page = next;
     return next;
@@ -2810,6 +3151,8 @@ async function render(doc, opts) {
   if (opts.count !== void 0) positive(opts.count, "count", true);
   const anim = opts.animation === void 0 ? void 0 : doc.animations.find((a) => a.id === opts.animation);
   if (opts.animation !== void 0 && !anim) throw new Error(`unknown animation "${opts.animation}"`);
+  if (opts.weightBone && !doc.bones.some((b) => b.id === opts.weightBone)) throw new Error(`unknown weight bone "${opts.weightBone}"`);
+  for (const src of Object.keys(opts.debugFillMasks ?? {})) if (!doc.assets.some((a) => a.src === src)) throw new Error(`fill mask refers to unknown texture "${src}"`);
   if (opts.times && (!opts.times.length || opts.times.some((t) => !Number.isFinite(t) || t < 0)))
     throw new Error("times must contain finite, nonnegative sample times");
   if (opts.region && (opts.region.length !== 4 || opts.region.some((v) => !Number.isFinite(v)) || opts.region[2] <= 0 || opts.region[3] <= 0))
@@ -2826,12 +3169,27 @@ async function render(doc, opts) {
     }
   }
   const assets = {};
+  const identity = { document: sha256(JSON.stringify(doc)), assets: {}, renderer: "", masks: {} };
   for (const a of doc.assets) {
     if (assets[a.src]) continue;
-    const buf = await readFile2(join3(opts.assetsDir, a.src));
+    let buf = await readFile3(join4(opts.assetsDir, a.src));
+    identity.assets[a.src] = sha256(buf);
+    if (opts.debugFillMasks?.[a.src]) {
+      const maskData = await readFile3(join4(opts.assetsDir, opts.debugFillMasks[a.src]));
+      identity.masks[opts.debugFillMasks[a.src]] = sha256(maskData);
+      const png = PNG.sync.read(buf), mask = PNG.sync.read(maskData);
+      if (png.width !== mask.width || png.height !== mask.height) throw new Error(`fill mask dimensions differ for ${a.src}`);
+      for (let i = 0; i < png.data.length; i += 4) if (mask.data[i] > 127 && mask.data[i + 3] > 0) {
+        png.data[i] = 255;
+        png.data[i + 1] = 0;
+        png.data[i + 2] = 255;
+      }
+      buf = PNG.sync.write(png);
+    }
     assets[a.src] = `data:${mime(a.src)};base64,${buf.toString("base64")}`;
   }
   const p = await getPage();
+  identity.renderer = sha256(harnessJs);
   const res = await p.evaluate(
     async ({ doc: doc2, assets: assets2, scale, ro }) => {
       const h = window.rigHarness;
@@ -2842,10 +3200,11 @@ async function render(doc, opts) {
       doc,
       assets,
       scale: opts.scale ?? 1,
-      ro: { animation: opts.animation, times: times2, overlayBones: opts.overlayBones, background: opts.background, sheetColumns: opts.sheetColumns, onionSkin: opts.onionSkin, region }
+      ro: { animation: opts.animation, times: times2, overlayBones: opts.overlayBones, background: opts.background, transparent: opts.transparent, weightBone: opts.weightBone, sheetColumns: opts.sheetColumns, onionSkin: opts.onionSkin, region }
     }
   );
   return {
+    identity,
     frames: res.frames.map(fromDataUrl),
     sheet: fromDataUrl(res.sheet),
     times: times2,
@@ -2854,6 +3213,146 @@ async function render(doc, opts) {
   };
 }
 
+// src/preview/export-video.ts
+async function exportVideo(doc, opts) {
+  const anim = doc.animations.find((a) => a.id === opts.animation), fps = opts.fps ?? 60;
+  if (!anim) throw new Error(`unknown animation "${opts.animation}"`);
+  if (!Number.isInteger(fps) || fps < 1 || fps > 240) throw new Error("video fps must be an integer between 1 and 240");
+  const count = Math.max(1, Math.round(anim.duration * fps));
+  if (count > 1e4) throw new Error("video exceeds 10000 frames; export shorter clips");
+  await mkdir2(dirname4(opts.outFile), { recursive: true });
+  const temp = await mkdtemp(join5(dirname4(opts.outFile), ".golem-video-"));
+  try {
+    for (let start = 0; start < count; start += 24) {
+      const times2 = Array.from({ length: Math.min(24, count - start) }, (_, i) => (start + i) / fps);
+      const rendered = await renderPreview(doc, { ...opts, transparent: false, times: times2 });
+      await Promise.all(rendered.frames.map((frame, i) => writeFile2(join5(temp, `${String(start + i).padStart(6, "0")}.png`), frame)));
+    }
+    const output = join5(temp, "preview.mp4");
+    const proc = spawn("ffmpeg", ["-hide_banner", "-loglevel", "error", "-y", "-framerate", String(fps), "-i", join5(temp, "%06d.png"), "-vf", "pad=ceil(iw/2)*2:ceil(ih/2)*2", "-c:v", "libx264", "-pix_fmt", "yuv420p", "-movflags", "+faststart", output], { stdio: ["ignore", "ignore", "pipe"] });
+    let diagnostic = "";
+    proc.stderr.on("data", (chunk) => {
+      diagnostic = (diagnostic + chunk).slice(-8e3);
+    });
+    const [code] = await once(proc, "close");
+    if (code !== 0) throw new Error(`MP4 encoder failed: ${diagnostic}`);
+    await rename3(output, opts.outFile);
+    return { frames: count, fps, duration: count / fps };
+  } finally {
+    await rm2(temp, { recursive: true, force: true });
+  }
+}
+
+// src/rig-quality.ts
+var values = (v) => typeof v === "number" ? [v] : Array.isArray(v) && v.every((n) => typeof n === "number") ? v : void 0;
+var delta = (a, b) => a.map((v, i) => v - b[i]);
+var magnitude = (a) => Math.max(0, ...a.map(Math.abs));
+function motionQuality(doc, anim, opts = {}) {
+  const out = [], D = anim.duration;
+  const report = (code, subject, message, time, level = "warn") => out.push({ level, code, subject, animation: anim.id, time, message });
+  for (const tr of anim.tracks) {
+    const id = `${tr.target}.${tr.id}.${tr.prop}`, looping = anim.loop && tr.keys[0].t === 0 && tr.keys.at(-1).t === D;
+    const at = (t) => sample(tr, t, looping), numeric = tr.keys.every((k) => values(k.v) !== void 0);
+    if (anim.loop) {
+      const first = at(0), last = at(D), av = values(first), bv = values(last);
+      const diff = av && bv && av.length === bv.length ? magnitude(delta(av, bv)) : first === last || JSON.stringify(first) === JSON.stringify(last) ? 0 : Infinity;
+      if (diff > 1e-3 && typeof first !== "number") report("loop_seam", id, `loop endpoint values differ (${Number.isFinite(diff) ? `max delta ${diff.toFixed(4)}` : "discrete state"}); all channels must close`);
+      if (numeric && diff <= 1e-3 && tr.keys.length > 1) {
+        const h = Math.min(D / 1e4, (tr.keys[1].t - tr.keys[0].t) / 100, (tr.keys.at(-1).t - tr.keys.at(-2).t) / 100);
+        const va = delta(values(at(h)), values(at(0))).map((v) => v / h), vb = delta(values(at(D)), values(at(D - h))).map((v) => v / h);
+        const dv = magnitude(delta(va, vb));
+        if (dv > Math.max(0.05, 0.05 * Math.max(magnitude(va), magnitude(vb)))) report("loop_velocity", id, `loop velocity changes by ${dv.toFixed(3)} units/s at the wrap`);
+      }
+    }
+    if (!numeric) continue;
+    for (let i = 1; i < tr.keys.length - 1; i++) {
+      const p = tr.keys[i - 1], k = tr.keys[i], n = tr.keys[i + 1];
+      if (p.ease === "step" || k.ease === "step") continue;
+      const h = Math.min(k.t - p.t, n.t - k.t) / 1e3;
+      const left = delta(values(at(k.t)), values(at(k.t - h))).map((v) => v / h), right = delta(values(at(k.t + h)), values(at(k.t))).map((v) => v / h);
+      const before = delta(values(k.v), values(p.v)), after = delta(values(n.v), values(k.v));
+      const pass = before.some((v, j2) => v * after[j2] > 1e-6);
+      const speed = Math.max(magnitude(before) / (k.t - p.t), magnitude(after) / (n.t - k.t));
+      if (pass && Math.max(magnitude(left), magnitude(right)) < speed * 0.02) report("pass_key_stop", id, `motion stops at a pass-through key; use track interpolation pchip or matched tangents`, k.t);
+      const jump = magnitude(delta(left, right));
+      if (jump > Math.max(0.1, speed * 0.1)) report("velocity_jump", id, `velocity jumps ${jump.toFixed(3)} units/s across this key`, k.t);
+      const acceleration = (a, b, c) => values(at(b)).map((v, j2) => (values(at(c))[j2] - 2 * v + values(at(a))[j2]) / (h * h));
+      const al = acceleration(k.t - 2 * h, k.t - h, k.t), ar = acceleration(k.t, k.t + h, k.t + 2 * h);
+      const aj = magnitude(delta(al, ar));
+      if (aj > Math.max(1, speed / Math.min(k.t - p.t, n.t - k.t) * 2)) report("acceleration_jump", id, `acceleration changes by ${aj.toFixed(2)} units/s\xB2 at this key; PCHIP guarantees velocity, not acceleration continuity`, k.t, "info");
+    }
+  }
+  const steps = Math.max(2, Math.ceil(D * 60));
+  const times2 = new Set(Array.from({ length: steps + 1 }, (_, i) => i * D / steps));
+  for (const tr of anim.tracks) for (const k of tr.keys) {
+    times2.add(k.t);
+    if (k.t > 0) times2.add(Math.max(0, k.t - 1e-5));
+  }
+  const samples = [...times2].sort((a, b) => a - b).map((t) => ({ t, pose: poseOf(anim, t) }));
+  for (const bone of opts.secondaryBones ?? []) {
+    if (!doc.bones.some((b) => b.id === bone)) throw new Error(`unknown secondary bone "${bone}"`);
+    const local = samples.map((s2) => evaluate(doc, s2.pose).bones.get(bone));
+    const curves = ["rotation", "x", "y"].map((prop) => local.map((b) => b[prop]));
+    if (curves.every((v) => Math.max(...v) - Math.min(...v) < 1e-3)) report("secondary_frozen", bone, `declared secondary bone has no local motion in this animation`);
+  }
+  const reported = /* @__PURE__ */ new Set();
+  for (const [front, back] of opts.frontOf ?? []) {
+    if (![front, back].every((id) => doc.slots.some((s2) => s2.id === id))) throw new Error(`unknown frontOf slots: ${front}, ${back}`);
+    for (const { t, pose } of samples) {
+      const skel = evaluate(doc, pose);
+      if (!skel.attachment.get(front) || !skel.attachment.get(back)) continue;
+      const visible = (id) => {
+        const slot = doc.slots.find((s2) => s2.id === id);
+        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"));
+      const z4 = (id) => order ? order.indexOf(id) : Number(pose.get(pk("slot", id, "z")) ?? doc.slots.find((s2) => s2.id === id).z);
+      const pair = JSON.stringify([front, back]);
+      if (z4(front) <= z4(back) && !reported.has(pair)) {
+        reported.add(pair);
+        report("draw_order_rule", front, `"${front}" must stay explicitly in front of "${back}" according to the brief (equal z is ambiguous)`, t);
+      }
+    }
+  }
+  for (const tr of anim.tracks.filter((t) => t.target === "slot" && t.prop === "attachment")) for (const key of tr.keys.filter((k) => k.t > 0)) {
+    const a = evaluate(doc, poseOf(anim, Math.max(0, key.t - 1e-6))), b = evaluate(doc, poseOf(anim, key.t));
+    const before = a.attachment.get(tr.id), after = b.attachment.get(tr.id);
+    if (!before || !after || before.id === after.id) continue;
+    const landmarksA = opts.landmarks?.[before.id], landmarksB = opts.landmarks?.[after.id];
+    if (!landmarksA && !landmarksB) continue;
+    if (!landmarksA || !landmarksB || !Object.keys(landmarksA).some((name) => landmarksB[name])) {
+      report("landmark_unmeasured", tr.id, `swap ${before.id} \u2192 ${after.id} has no shared declared landmarks`, key.t);
+      continue;
+    }
+    const point = (skel, att, uv) => {
+      if (att.type === "region") {
+        const [w, h] = regionSize(doc, att);
+        return apply(regionMatrix(skel, att.slot, att), (uv[0] - 0.5) * w, (uv[1] - 0.5) * h);
+      }
+      if (att.type !== "mesh") return;
+      const v = attachmentWorldVertices(skel, att.slot, att);
+      for (let i = 0; i < att.triangles.length; i += 3) {
+        const [ia, ib, ic] = att.triangles.slice(i, i + 3), ux = att.uvs[ia * 2], uy = att.uvs[ia * 2 + 1], bx = att.uvs[ib * 2] - ux, by = att.uvs[ib * 2 + 1] - uy, cx = att.uvs[ic * 2] - ux, cy = att.uvs[ic * 2 + 1] - uy, det = bx * cy - by * cx;
+        if (Math.abs(det) < 1e-12) continue;
+        const s2 = ((uv[0] - ux) * cy - (uv[1] - uy) * cx) / det, r = (bx * (uv[1] - uy) - by * (uv[0] - ux)) / det;
+        if (s2 >= -1e-6 && r >= -1e-6 && s2 + r <= 1 + 1e-6) return [v[ia * 2] * (1 - s2 - r) + v[ib * 2] * s2 + v[ic * 2] * r, v[ia * 2 + 1] * (1 - s2 - r) + v[ib * 2 + 1] * s2 + v[ic * 2 + 1] * r];
+      }
+    };
+    for (const [name, uv] of Object.entries(landmarksA)) if (landmarksB[name]) {
+      const p = point(a, before, uv), q = point(b, after, landmarksB[name]);
+      if (!p || !q) {
+        report("landmark_unmeasured", tr.id, `landmark "${name}" is outside attachment geometry`, key.t);
+        continue;
+      }
+      const distance = Math.hypot(p[0] - q[0], p[1] - q[1]);
+      if (distance > (opts.landmarkTolerance ?? 2)) report("attachment_landmark_jump", tr.id, `"${name}" moves ${distance.toFixed(2)}px when ${before.id} changes to ${after.id}`, key.t);
+    }
+  }
+  return out;
+}
+
 // src/rig-check.ts
 var FOLD_ERROR_RATIO = 0.05;
 var IK_SLACK = 1;
@@ -2862,17 +3361,25 @@ var isNumeric = (t) => t.target !== "slot" || t.prop !== "attachment";
 var trackId3 = (t) => `${t.target}.${t.id}.${t.prop}`;
 var fmt = (n) => String(Math.round(n * 1e3) / 1e3);
 var times = (a, fps) => {
-  const n = Math.max(1, Math.round(a.duration * fps)), out = [];
-  for (let i = 0; i <= n; i++) out.push(Math.min(a.duration, i / fps));
+  const n = Math.max(1, Math.ceil(a.duration * fps)), out = [];
+  for (let i = 0; i <= n; i++) out.push(a.duration * i / n);
   return out;
 };
 function checkRig(doc, opts = {}) {
   const fps = opts.fps ?? 30, dfps = opts.deformFps ?? 60, overlapMin = opts.overlap ?? 0.6, margin = opts.margin ?? 1;
+  if (![fps, dfps].every((v) => Number.isFinite(v) && v > 0)) throw new Error("check sampling rates must be positive");
   const anims = opts.animation === void 0 ? doc.animations : doc.animations.filter((a) => a.id === opts.animation);
   if (opts.animation !== void 0 && !anims.length) throw new Error(`unknown animation "${opts.animation}"`);
   const out = [];
+  for (const e of constraintDependencies(doc).edges.filter((e2) => e2.late)) out.push({
+    level: "warn",
+    code: "constraint_order",
+    subject: e.reader,
+    message: `constraint "${e.reader}" reads bone "${e.bone}" before later constraint "${e.writer}" moves it; use rig_order_constraints or set explicit order`
+  });
   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((s2) => s2.id === slotId), alphaV = pose.get(`slot:${slotId}:alpha`);
@@ -3042,6 +3549,7 @@ function checkRig(doc, opts = {}) {
     return rest;
   };
   for (const a of anims) {
+    out.push(...motionQuality(doc, a, opts));
     for (const t of a.tracks) {
       if (!isNumeric(t)) continue;
       const vals = t.keys.map((k) => k.v);
@@ -3070,6 +3578,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();
@@ -3149,7 +3658,9 @@ function checkRig(doc, opts = {}) {
         if (!sorted.length) continue;
         const typical = sorted[Math.floor(sorted.length / 2)];
         const worst2 = ds.reduce((m, x) => x.d > m.d ? x : m, ds[0]);
-        if (worst2.d > Math.max(6, 5 * typical)) {
+        const index = ds.indexOf(worst2);
+        const neighbours = Math.max(ds[index - 1]?.d ?? 0, ds[index + 1]?.d ?? 0);
+        if (worst2.d > Math.max(6, 5 * typical, 3 * neighbours)) {
           const stepped = stepTimes.some((st) => st > worst2.t - 1 / dfps - 1e-9 && st <= worst2.t + 1e-9);
           out.push({
             level: stepped ? "info" : "warn",
@@ -3200,7 +3711,7 @@ function checkRig(doc, opts = {}) {
   for (const att of doc.attachments) {
     if (att.type !== "region") continue;
     const asset = doc.assets.find((a) => a.id === att.asset), bbox = asset?.origin?.bbox;
-    if (!asset || !bbox || !doc.slots.some((s2) => s2.id === att.slot)) continue;
+    if (!asset || !bbox || asset.origin?.bboxSpace === "source" || !doc.slots.some((s2) => s2.id === att.slot)) continue;
     const [cx, cy] = apply(regionMatrix(restWorld, att.slot, att), 0, 0);
     const ex = bbox[0] + bbox[2] / 2, ey = bbox[1] + bbox[3] / 2, dx = cx - ex, dy = cy - ey;
     const dist = Math.hypot(dx, dy);
@@ -3245,7 +3756,8 @@ function checkRig(doc, opts = {}) {
   for (const att of doc.attachments) if (att.type !== "path" && shownAttachments.has(att.id)) used.add(att.asset);
   for (const asset of doc.assets) if (!used.has(asset.id))
     out.push({ level: "info", code: "unused_asset", subject: asset.id, message: `asset "${asset.id}" is not shown by any attachment at rest or in any animation` });
-  for (const s2 of doc.slots) if (!s2.attachment && !swappedIn.has(s2.id))
+  const maskSlots = new Set(doc.slots.flatMap((s2) => s2.clip ? [doc.attachments.find((a) => a.id === s2.clip)?.slot] : []));
+  for (const s2 of doc.slots) if (!s2.attachment && !swappedIn.has(s2.id) && !maskSlots.has(s2.id))
     out.push({ level: "warn", code: "never_visible", subject: s2.id, message: `slot "${s2.id}" has no attachment and no animation ever shows one` });
   return out;
 }
@@ -3273,14 +3785,14 @@ function summarize(findings, max = 12) {
 }
 
 // src/rig-history.ts
-import { mkdir as mkdir2, readdir as readdir2, readFile as readFile3, writeFile as writeFile2, unlink } from "node:fs/promises";
-import { basename as basename3, dirname as dirname3, join as join4 } from "node:path";
+import { mkdir as mkdir3, readdir as readdir3, readFile as readFile4, writeFile as writeFile3, unlink } from "node:fs/promises";
+import { basename as basename3, dirname as dirname5, join as join6 } from "node:path";
 function historyDir(rigPath) {
-  return join4(dirname3(rigPath), ".rig-history", basename3(rigPath).replace(/\.json$/, ""));
+  return join6(dirname5(rigPath), ".rig-history", basename3(rigPath).replace(/\.json$/, ""));
 }
 async function files(dir) {
   try {
-    return (await readdir2(dir)).filter((f) => /^\d{4,}\.json$/.test(f)).sort((a, b) => Number(a.slice(0, -5)) - Number(b.slice(0, -5)));
+    return (await readdir3(dir)).filter((f) => /^\d{4,}\.json$/.test(f)).sort((a, b) => Number(a.slice(0, -5)) - Number(b.slice(0, -5)));
   } catch {
     return [];
   }
@@ -3289,22 +3801,22 @@ async function snapshots(rigPath) {
   return files(historyDir(rigPath));
 }
 async function listHistory(rigPath) {
-  return (await snapshots(rigPath)).map((f) => join4(historyDir(rigPath), f));
+  return (await snapshots(rigPath)).map((f) => join6(historyDir(rigPath), f));
 }
-var redoDir = (rigPath) => join4(historyDir(rigPath), "redo");
+var redoDir = (rigPath) => join6(historyDir(rigPath), "redo");
 async function listRedo(rigPath) {
-  return (await files(redoDir(rigPath))).map((f) => join4(redoDir(rigPath), f));
+  return (await files(redoDir(rigPath))).map((f) => join6(redoDir(rigPath), f));
 }
 async function clearRedo(rigPath) {
   for (const f of await listRedo(rigPath)) await unlink(f);
 }
 async function pushInto(dir, contents, keep) {
-  await mkdir2(dir, { recursive: true });
+  await mkdir3(dir, { recursive: true });
   const fs = await files(dir);
   const next = fs.length ? +fs[fs.length - 1].slice(0, -5) + 1 : 1;
-  const file = join4(dir, `${String(next).padStart(4, "0")}.json`);
-  await writeFile2(file, contents);
-  for (const f of fs.slice(0, Math.max(0, fs.length + 1 - keep))) await unlink(join4(dir, f));
+  const file = join6(dir, `${String(next).padStart(4, "0")}.json`);
+  await writeFile3(file, contents);
+  for (const f of fs.slice(0, Math.max(0, fs.length + 1 - keep))) await unlink(join6(dir, f));
   return file;
 }
 async function pushHistory(rigPath, contents, keep = 50, opts = {}) {
@@ -3317,12 +3829,12 @@ async function popHistory(rigPath, steps = 1) {
   if (!Number.isInteger(steps) || steps < 1 || steps > files2.length)
     throw new Error(`only ${files2.length} snapshot${files2.length === 1 ? "" : "s"} available, cannot undo ${steps}`);
   const dir = historyDir(rigPath);
-  const contents = await readFile3(join4(dir, files2[files2.length - steps]), "utf8");
-  for (const f of files2.slice(files2.length - steps)) await unlink(join4(dir, f));
+  const contents = await readFile4(join6(dir, files2[files2.length - steps]), "utf8");
+  for (const f of files2.slice(files2.length - steps)) await unlink(join6(dir, f));
   return contents;
 }
 async function undo(rigPath, steps = 1) {
-  const current = await readFile3(rigPath, "utf8");
+  const current = await readFile4(rigPath, "utf8");
   const restored = await popHistory(rigPath, steps);
   await pushInto(redoDir(rigPath), current, 50);
   return restored;
@@ -3331,8 +3843,8 @@ async function redo(rigPath) {
   const entries2 = await listRedo(rigPath);
   if (!entries2.length) throw new Error("nothing to redo");
   const file = entries2[entries2.length - 1];
-  const contents = await readFile3(file, "utf8");
-  await pushHistory(rigPath, await readFile3(rigPath, "utf8"), 50, { keepRedo: true });
+  const contents = await readFile4(file, "utf8");
+  await pushHistory(rigPath, await readFile4(rigPath, "utf8"), 50, { keepRedo: true });
   await unlink(file);
   return contents;
 }
@@ -3403,11 +3915,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);
@@ -3426,9 +3940,9 @@ function diffDocs(a, b) {
 }
 
 // src/rig-atlas.ts
-import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
-import { join as join5 } from "node:path";
-import { PNG } from "pngjs";
+import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile4 } from "node:fs/promises";
+import { join as join7 } from "node:path";
+import { PNG as PNG2 } from "pngjs";
 function packRects(rects, opts = {}) {
   const extrude = opts.extrude ?? 1, pad = Math.max(opts.padding ?? 2, 2 * extrude), max = opts.maxSize ?? 4096;
   const sorted = [...rects].sort((a, b) => b.height - a.height || b.width - a.width || a.id.localeCompare(b.id));
@@ -3486,10 +4000,10 @@ async function buildAtlas(doc, assetsDir, outDir, opts = {}) {
   for (const a of doc.assets) {
     if (!/\.png$/i.test(a.src)) throw new Error(`atlas requires PNG assets: "${a.src}" (asset "${a.id}") is not a PNG`);
     let png = files2.get(a.src);
-    if (!png) files2.set(a.src, png = PNG.sync.read(await readFile4(join5(assetsDir, a.src))));
+    if (!png) files2.set(a.src, png = PNG2.sync.read(await readFile5(join7(assetsDir, a.src))));
     if (a.frame) {
-      const [fx, fy, fw, fh] = a.frame, sub = new PNG({ width: fw, height: fh });
-      PNG.bitblt(png, sub, fx, fy, fw, fh, 0, 0);
+      const [fx, fy, fw, fh] = a.frame, sub = new PNG2({ width: fw, height: fh });
+      PNG2.bitblt(png, sub, fx, fy, fw, fh, 0, 0);
       png = sub;
     }
     if (png.width !== a.width || png.height !== a.height)
@@ -3497,26 +4011,26 @@ async function buildAtlas(doc, assetsDir, outDir, opts = {}) {
     images.set(a.id, png);
   }
   const packed = packRects(doc.assets.map((a) => ({ id: a.id, width: a.width, height: a.height })), opts);
-  const sheet = new PNG({ width: packed.width, height: packed.height });
+  const sheet = new PNG2({ width: packed.width, height: packed.height });
   for (const [id, [x, y, w, h]] of packed.frames) {
-    PNG.bitblt(images.get(id), sheet, 0, 0, w, h, x, y);
+    PNG2.bitblt(images.get(id), sheet, 0, 0, w, h, x, y);
     extrudeFrame(sheet, x, y, w, h, opts.extrude ?? 1);
   }
-  await mkdir3(outDir, { recursive: true });
-  await writeFile3(join5(outDir, "atlas.png"), PNG.sync.write(sheet));
+  await mkdir4(outDir, { recursive: true });
+  await writeFile4(join7(outDir, "atlas.png"), PNG2.sync.write(sheet));
   const out = { ...doc, assets: doc.assets.map((a) => ({ ...a, src: "atlas.png", frame: packed.frames.get(a.id) })) };
-  await saveJson(join5(outDir, "rig.json"), out);
+  await saveJson(join7(outDir, "rig.json"), out);
   return out;
 }
 
 // src/spine-import.ts
-import { readFile as readFile6, stat, writeFile as writeFile4 } from "node:fs/promises";
-import { basename as basename4, dirname as dirname4, extname, join as join6, relative } from "node:path";
+import { readFile as readFile7, stat, writeFile as writeFile5 } from "node:fs/promises";
+import { basename as basename4, dirname as dirname6, extname, join as join8, relative } from "node:path";
 
 // src/ktx2.ts
-import { readFile as readFile5 } from "node:fs/promises";
+import { readFile as readFile6 } from "node:fs/promises";
 import { createRequire } from "node:module";
-import { PNG as PNG2 } from "pngjs";
+import { PNG as PNG3 } from "pngjs";
 var require2 = createRequire(import.meta.url);
 var basisPromise;
 async function basis2() {
@@ -3528,8 +4042,8 @@ async function basis2() {
     } catch {
       throw new Error("KTX2 pages need the basis transcoder from three.js: `npm i -D three`, or convert the page to PNG yourself");
     }
-    const wasm = await readFile5(jsPath.replace(/\.js$/, ".wasm"));
-    const src = await readFile5(jsPath, "utf8");
+    const wasm = await readFile6(jsPath.replace(/\.js$/, ".wasm"));
+    const src = await readFile6(jsPath, "utf8");
     const mod = { exports: {} };
     new Function("require", "module", "exports", "__dirname", "__filename", src)(require2, mod, mod.exports, jsPath.replace(/\/[^/]+$/, ""), jsPath);
     const Basis = await mod.exports({ wasmBinary: wasm });
@@ -3556,9 +4070,9 @@ async function ktx2ToRgba(data) {
 }
 async function ktx2ToPng(data) {
   const { rgba, ...info } = await ktx2ToRgba(data);
-  const png = new PNG2({ width: info.width, height: info.height });
+  const png = new PNG3({ width: info.width, height: info.height });
   png.data = Buffer.from(rgba.buffer, rgba.byteOffset, rgba.byteLength);
-  return { ...info, png: PNG2.sync.write(png) };
+  return { ...info, png: PNG3.sync.write(png) };
 }
 
 // src/spine-import.ts
@@ -3698,9 +4212,9 @@ function importSpine(json, atlasText, opts = {}) {
   };
   const sequences = /* @__PURE__ */ new Map();
   const skinnedName = /* @__PURE__ */ new Map();
-  for (const skin of skins) {
-    const prefix = skin.name === "default" ? "" : `${skin.name}_`;
-    for (const [slotName, atts] of Object.entries(skin.attachments ?? {}))
+  for (const skin2 of skins) {
+    const prefix = skin2.name === "default" ? "" : `${skin2.name}_`;
+    for (const [slotName, atts] of Object.entries(skin2.attachments ?? {}))
       for (const [name, a] of Object.entries(atts)) {
         const key = `${slotName} ${name}`;
         const seq = a.sequence;
@@ -3765,11 +4279,11 @@ function importSpine(json, atlasText, opts = {}) {
     }
     return { weights };
   };
-  for (const skin of skins) {
-    const prefix = skin.name === "default" ? "" : `${skin.name}_`;
-    for (const [slotName, atts] of Object.entries(skin.attachments ?? {})) {
+  for (const skin2 of skins) {
+    const prefix = skin2.name === "default" ? "" : `${skin2.name}_`;
+    for (const [slotName, atts] of Object.entries(skin2.attachments ?? {})) {
       if (!slotIndexByName.has(slotName)) {
-        warnings.push(`skin "${skin.name}": unknown slot "${slotName}"`);
+        warnings.push(`skin "${skin2.name}": unknown slot "${slotName}"`);
         continue;
       }
       const slot = slotIds.get(slotName);
@@ -4100,9 +4614,9 @@ function importSpine(json, atlasText, opts = {}) {
       const attFrames = attachmentFrames.get(slotName);
       const setupName = spineSlots.find((x) => x.name === slotName)?.attachment ?? null;
       const at = (xs, t) => {
-        let hit;
-        for (const x of xs) if (x.t <= t + 1e-9) hit = x;
-        return hit;
+        let hit2;
+        for (const x of xs) if (x.t <= t + 1e-9) hit2 = x;
+        return hit2;
       };
       const shownAt = (t) => {
         let name = setupName;
@@ -4208,21 +4722,21 @@ async function firstExisting(candidates, what) {
   throw new Error(`${what} not found, tried: ${candidates.join(", ")}`);
 }
 async function importSpineProject(opts) {
-  const json = JSON.parse(await readFile6(opts.json, "utf8"));
+  const json = JSON.parse(await readFile7(opts.json, "utf8"));
   const stem = opts.json.replace(/\.json$/i, "");
   const atlasPath = opts.atlas ?? await firstExisting([stem + ".atlas", stem + ".atlas.txt"], "atlas");
-  const atlasText = await readFile6(atlasPath, "utf8");
+  const atlasText = await readFile7(atlasPath, "utf8");
   const { pages } = parseAtlas(atlasText);
   if (pages.length !== 1) throw new Error(`expected one atlas page, got ${pages.length}`);
-  const pageStem = join6(dirname4(atlasPath), pages[0].name.replace(/\.[a-z0-9]+$/i, ""));
-  const imagePath = opts.image ?? await firstExisting([join6(dirname4(atlasPath), pages[0].name), pageStem + ".png", pageStem + ".ktx2", stem + ".png", stem + ".ktx2"], "atlas page image");
-  const rigDir = dirname4(opts.rigPath);
+  const pageStem = join8(dirname6(atlasPath), pages[0].name.replace(/\.[a-z0-9]+$/i, ""));
+  const imagePath = opts.image ?? await firstExisting([join8(dirname6(atlasPath), pages[0].name), pageStem + ".png", pageStem + ".ktx2", stem + ".png", stem + ".ktx2"], "atlas page image");
+  const rigDir = dirname6(opts.rigPath);
   let pngPath = imagePath;
   if (extname(imagePath).toLowerCase() === ".ktx2") {
-    pngPath = join6(rigDir, basename4(imagePath).replace(/\.ktx2$/i, ".png"));
+    pngPath = join8(rigDir, basename4(imagePath).replace(/\.ktx2$/i, ".png"));
     if (!await exists(pngPath)) {
-      const { png } = await ktx2ToPng(new Uint8Array(await readFile6(imagePath)));
-      await writeFile4(pngPath, png);
+      const { png } = await ktx2ToPng(new Uint8Array(await readFile7(imagePath)));
+      await writeFile5(pngPath, png);
     }
   }
   const pageImage = relative(rigDir, pngPath).split("\\").join("/");
@@ -4244,7 +4758,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;
     }
@@ -4342,11 +4856,11 @@ function describeTemplate(t) {
 }
 
 // src/rig-template-library.ts
-import { readFile as readFile7, writeFile as writeFile5, mkdir as mkdir4 } from "node:fs/promises";
-import { dirname as dirname5 } from "node:path";
+import { readFile as readFile8, writeFile as writeFile6, mkdir as mkdir5 } from "node:fs/promises";
+import { dirname as dirname7 } from "node:path";
 async function loadLibrary(path) {
   try {
-    return JSON.parse(await readFile7(path, "utf8"));
+    return JSON.parse(await readFile8(path, "utf8"));
   } catch (e) {
     if (e.code === "ENOENT") return [];
     throw e;
@@ -4357,14 +4871,14 @@ async function saveTemplate(path, tpl) {
   const i = all.findIndex((t) => t.name === tpl.name);
   if (i >= 0) all[i] = tpl;
   else all.push(tpl);
-  await mkdir4(dirname5(path), { recursive: true });
-  await writeFile5(path, JSON.stringify(all, null, 2));
+  await mkdir5(dirname7(path), { recursive: true });
+  await writeFile6(path, JSON.stringify(all, null, 2));
 }
 
 // src/rig-mesh-image.ts
-import { PNG as PNG3 } from "pngjs";
+import { PNG as PNG4 } from "pngjs";
 function alphaMaskFromPng(buf, frame) {
-  const png = PNG3.sync.read(buf);
+  const png = PNG4.sync.read(buf);
   const [fx, fy, w, h] = frame ?? [0, 0, png.width, png.height];
   if (fx < 0 || fy < 0 || w < 1 || h < 1 || fx + w > png.width || fy + h > png.height) {
     throw new Error(`frame [${fx}, ${fy}, ${w}, ${h}] is outside the ${png.width}x${png.height} image`);
@@ -4374,11 +4888,526 @@ function alphaMaskFromPng(buf, frame) {
   return { width: w, height: h, alpha };
 }
 
+// src/rig-gates.ts
+import { z as z2 } from "zod";
+
+// src/rig-state.ts
+var AnimationState = class {
+  constructor(sink, opts = {}) {
+    this.sink = sink;
+    this.opts = opts;
+    this.defaultMix = opts.mix ?? 0;
+  }
+  onEvent;
+  base;
+  main;
+  queue = [];
+  overlays = /* @__PURE__ */ new Map();
+  /** last composed pose without overlays — mix snapshots start here */
+  pose = /* @__PURE__ */ new Map();
+  from;
+  mixLeft = 0;
+  mixTotal = 0;
+  /** a mix begun in this update shows weight 0 for the frame it starts on */
+  mixFresh = false;
+  defaultMix;
+  /** id of the animation currently shown (main, else base) */
+  get current() {
+    return (this.main ?? this.base)?.anim.id;
+  }
+  get baseId() {
+    return this.base?.anim.id;
+  }
+  channel(id, loop, priority = 0) {
+    const anim = this.sink.doc.animations.find((a) => a.id === id);
+    if (!anim) {
+      const message = `unknown animation "${id}"; available: ${this.sink.doc.animations.map((a) => a.id).join(", ")}`;
+      if (this.opts.missingAnimation === "throw") throw new Error(message);
+      (this.opts.onWarning ?? console.warn)(message);
+      return void 0;
+    }
+    return { anim, time: 0, loop: loop ?? anim.loop, done: false, priority, fresh: true };
+  }
+  setBase(id, opts = {}) {
+    const next = id === void 0 ? void 0 : this.channel(id);
+    if (id !== void 0 && !next) return;
+    this.base = next;
+    if (!this.main || this.main.done) {
+      this.main = void 0;
+      this.beginMix(opts.mix);
+      this.update(0);
+    }
+  }
+  play(id, opts = {}) {
+    const ch = this.channel(id, opts.loop, opts.priority ?? 0);
+    if (!ch) {
+      this.main?.settle?.("interrupted");
+      for (const queued of this.queue) queued.settle?.("dropped");
+      this.main = void 0;
+      this.queue = [];
+      this.beginMix(opts.mix);
+      this.update(0);
+      opts.onComplete?.("dropped");
+      return Promise.resolve("dropped");
+    }
+    const promise = new Promise((resolve4) => {
+      ch.settle = (r) => {
+        ch.settle = void 0;
+        opts.onComplete?.(r);
+        resolve4(r);
+      };
+    });
+    const cur = this.main, busy = cur !== void 0 && !cur.done, mode = opts.ifBusy ?? "queue";
+    if (!busy || mode === "interrupt" || ch.priority >= cur.priority) {
+      if (busy) cur.settle?.("interrupted");
+      this.main = ch;
+      this.beginMix(opts.mix);
+      this.update(0);
+    } else if (mode === "drop") ch.settle("dropped");
+    else this.queue.push(ch);
+    return promise;
+  }
+  /** Independent loop on top of the shown pose; `undefined` removes it. */
+  setOverlay(name, id) {
+    if (id === void 0) this.overlays.delete(name);
+    else {
+      const ch = this.channel(id);
+      if (ch) this.overlays.set(name, ch);
+    }
+  }
+  /** Clear everything and show the setup pose. Pending plays resolve as "stopped". */
+  stop() {
+    this.main?.settle?.("stopped");
+    for (const ch of this.queue) ch.settle?.("stopped");
+    this.main = this.base = void 0;
+    this.queue = [];
+    this.overlays.clear();
+    this.from = void 0;
+    this.mixLeft = this.mixTotal = 0;
+    this.mixFresh = false;
+    this.pose = /* @__PURE__ */ new Map();
+    this.sink.setPose(/* @__PURE__ */ new Map());
+  }
+  update(dt) {
+    if (this.base) this.advance(this.base, dt, this.main === void 0);
+    if (this.main) {
+      const wasDone = this.main.done;
+      this.advance(this.main, dt, true);
+      if (this.main.done && !wasDone) {
+        this.main.settle?.("completed");
+        const next = this.queue.shift();
+        if (next || this.base) {
+          this.main = next;
+          this.beginMix();
+        }
+      }
+    }
+    const shown = this.main ?? this.base;
+    let pose = shown ? poseOf(shown.anim, shown.time) : /* @__PURE__ */ new Map();
+    if (this.from) {
+      if (!this.mixFresh) this.mixLeft = Math.max(0, this.mixLeft - dt);
+      this.mixFresh = false;
+      const w = this.mixTotal > 0 ? 1 - this.mixLeft / this.mixTotal : 1;
+      pose = blendPoses(this.from, pose, w, (k) => restValue(this.sink.doc, k));
+      if (this.mixLeft === 0) this.from = void 0;
+    }
+    this.pose = pose;
+    if (this.overlays.size) {
+      pose = new Map(pose);
+      for (const [name, ov] of this.overlays) {
+        this.advance(ov, dt, false);
+        poseOf(ov.anim, ov.time, pose);
+        if (ov.done) this.overlays.delete(name);
+      }
+    }
+    this.sink.setPose(pose);
+  }
+  beginMix(mix = this.defaultMix) {
+    if (mix > 0) {
+      this.from = new Map(this.pose);
+      this.mixLeft = this.mixTotal = mix;
+      this.mixFresh = true;
+    } else {
+      this.from = void 0;
+      this.mixLeft = this.mixTotal = 0;
+      this.mixFresh = false;
+    }
+  }
+  advance(ch, dt, emit) {
+    if (ch.done) return;
+    const prev = ch.fresh ? -1 : ch.time, d = ch.anim.duration;
+    ch.fresh = false;
+    ch.time += dt;
+    if (emit) {
+      for (const e of ch.anim.events) if (hit(e.t, prev, ch.time, d, ch.loop)) this.onEvent?.(e.name, e.payload);
+    }
+    if (ch.time >= d) {
+      if (ch.loop) ch.time %= d;
+      else {
+        ch.time = d;
+        ch.done = true;
+      }
+    }
+  }
+};
+function hit(t, prev, cur, d, loop) {
+  if (cur < d || !loop) return t > prev && t <= cur;
+  return t > prev && t <= d || t <= cur % d;
+}
+
+// src/rig-gates.ts
+var Limit = z2.number().nonnegative().optional();
+var Window = z2.tuple([z2.number().nonnegative(), z2.number().nonnegative()]).optional();
+var GateConfig = z2.object({
+  animation: z2.string(),
+  fps: z2.number().int().min(1).max(240).default(60),
+  requiredAnimations: z2.array(z2.string()).default([]),
+  motion: z2.array(z2.object({ bone: z2.string(), channel: z2.enum(["position", "rotation"]).default("position"), space: z2.enum(["world", "local"]).default("world"), minAmplitude: Limit, maxSpeed: Limit, maxAcceleration: Limit, maxJerk: Limit, maxStep: Limit, maxSetupDrift: Limit, during: Window })).default([]),
+  distances: z2.array(z2.object({ a: z2.string(), b: z2.string(), min: Limit, max: Limit, minRatio: Limit, maxRatio: Limit, during: Window })).default([]),
+  conditions: z2.array(z2.object({ whenSlotVisible: z2.string(), bone: z2.string(), prop: z2.enum(["x", "y", "rotation"]), space: z2.enum(["world", "local"]).default("world"), min: z2.number().optional(), max: z2.number().optional(), required: z2.boolean().default(true) })).default([]),
+  transitions: z2.array(z2.object({ from: z2.string(), to: z2.string(), fromTime: z2.number().nonnegative().default(0), mix: z2.number().nonnegative().default(0.18), maxStep: z2.number().nonnegative(), duration: z2.number().positive().default(0.5) })).default([])
+}).strict();
+var norm = (v) => Math.hypot(...v);
+var subtract = (a, b) => a.map((v, i) => v - b[i]);
+var wrap = (v) => ((v + 180) % 360 + 360) % 360 - 180;
+function runGates(doc, config) {
+  const cfg = GateConfig.parse(config), animation = doc.animations.find((a) => a.id === cfg.animation);
+  if (!animation) throw new Error(`unknown animation "${cfg.animation}"`);
+  if (!cfg.requiredAnimations.length && !cfg.motion.length && !cfg.distances.length && !cfg.conditions.length && !cfg.transitions.length) throw new Error("gate config needs at least one explicit rule");
+  const failures = [];
+  const metrics = {};
+  for (const id of cfg.requiredAnimations) if (!doc.animations.some((a) => a.id === id)) failures.push(`required animation missing: ${id}`);
+  const n = Math.max(1, Math.ceil(animation.duration * cfg.fps)), dt = animation.duration / n;
+  const frames = Array.from({ length: n + 1 }, (_, i) => {
+    const t = i * dt, pose = poseOf(animation, t);
+    return { t, pose, skel: evaluate(doc, pose) };
+  });
+  const rest = evaluate(doc, /* @__PURE__ */ new Map());
+  const bone = (s2, id, channel, space) => {
+    const b = s2.bones.get(id);
+    if (!b) throw new Error(`unknown gate bone "${id}"`);
+    return channel === "rotation" ? [space === "local" ? b.rotation : Math.atan2(b.world.b, b.world.a) * 180 / Math.PI] : space === "local" ? [b.x, b.y] : [b.world.tx, b.world.ty];
+  };
+  const inside = (t, w) => !w || t >= w[0] - 1e-9 && t <= w[1] + 1e-9;
+  const windowCheck = (w) => {
+    if (w && (w[0] > w[1] || w[1] > animation.duration)) throw new Error("invalid gate time window");
+  };
+  for (const rule of cfg.motion) {
+    if ([rule.minAmplitude, rule.maxSpeed, rule.maxAcceleration, rule.maxJerk, rule.maxStep, rule.maxSetupDrift].every((v) => v === void 0)) throw new Error("motion gate needs an explicit threshold");
+    windowCheck(rule.during);
+    const fs = frames.filter((f) => inside(f.t, rule.during));
+    if (fs.length < 4) throw new Error(`motion gate ${rule.bone} needs at least four samples`);
+    const vs = fs.map((f) => bone(f.skel, rule.bone, rule.channel, rule.space));
+    if (rule.channel === "rotation") for (let i = 1; i < vs.length; i++) vs[i][0] = vs[i - 1][0] + wrap(vs[i][0] - vs[i - 1][0]);
+    const derivative = (xs) => xs.slice(1).map((v, i) => subtract(v, xs[i]).map((v2) => v2 / dt));
+    const velocity = derivative(vs), acceleration = derivative(velocity), jerk = derivative(acceleration);
+    const range = vs[0].map((_, i) => Math.max(...vs.map((v) => v[i])) - Math.min(...vs.map((v) => v[i])));
+    const setup = bone(rest, rule.bone, rule.channel, rule.space);
+    const m = { samples: vs.length, amplitude: norm(range), speed: Math.max(...velocity.map(norm)), acceleration: Math.max(...acceleration.map(norm)), jerk: Math.max(...jerk.map(norm)), step: Math.max(...velocity.map(norm)) * dt, setupDrift: Math.max(...vs.map((v) => norm(subtract(v, setup)))) };
+    const id = `${rule.bone}.${rule.channel}.${rule.space}`;
+    metrics[id] = m;
+    if (rule.minAmplitude !== void 0 && m.amplitude < rule.minAmplitude) failures.push(`${id}: amplitude ${m.amplitude} < ${rule.minAmplitude}`);
+    for (const [limit, key] of [["maxSpeed", "speed"], ["maxAcceleration", "acceleration"], ["maxJerk", "jerk"], ["maxStep", "step"], ["maxSetupDrift", "setupDrift"]])
+      if (rule[limit] !== void 0 && m[key] > rule[limit]) failures.push(`${id}: ${key} ${m[key]} > ${rule[limit]}`);
+  }
+  for (const rule of cfg.distances) {
+    if ([rule.min, rule.max, rule.minRatio, rule.maxRatio].every((v) => v === void 0)) throw new Error("distance gate needs an explicit threshold");
+    windowCheck(rule.during);
+    const fs = frames.filter((f) => inside(f.t, rule.during));
+    if (!fs.length) throw new Error("distance gate has no samples");
+    const distance = (s2) => norm(subtract(bone(s2, rule.a, "position", "world"), bone(s2, rule.b, "position", "world")));
+    const setup = distance(rest), values2 = fs.map((f) => distance(f.skel)), lo = Math.min(...values2), hi = Math.max(...values2);
+    metrics[`${rule.a}-${rule.b}`] = { samples: fs.length, min: lo, max: hi, setup };
+    if ((rule.minRatio !== void 0 || rule.maxRatio !== void 0) && setup < 1e-9) throw new Error("distance ratio needs noncoincident setup landmarks");
+    if (rule.min !== void 0 && lo < rule.min || rule.max !== void 0 && hi > rule.max || rule.minRatio !== void 0 && lo < setup * rule.minRatio || rule.maxRatio !== void 0 && hi > setup * rule.maxRatio) failures.push(`distance ${rule.a}-${rule.b} outside allowed range`);
+  }
+  for (const rule of cfg.conditions) {
+    if (rule.min === void 0 && rule.max === void 0) throw new Error("condition gate needs an explicit threshold");
+    const slot = doc.slots.find((s2) => s2.id === rule.whenSlotVisible);
+    if (!slot) throw new Error(`unknown gate slot "${rule.whenSlotVisible}"`);
+    const ts = new Set(frames.map((f) => f.t));
+    for (const tr of animation.tracks) for (const k of tr.keys) {
+      ts.add(k.t);
+      if (k.t > 0) ts.add(Math.max(0, k.t - 1e-6));
+    }
+    let active2 = 0, bad = 0;
+    for (const t of ts) {
+      const pose = poseOf(animation, t), s2 = evaluate(doc, pose);
+      const color = s2.pose.get(pk("slot", slot.id, "color")) ?? colorToArray(slot.color);
+      const alpha = Number(s2.pose.get(pk("slot", slot.id, "alpha")) ?? slot.alpha) * color[3];
+      if (!s2.attachment.get(slot.id) || alpha <= 0.01) continue;
+      active2++;
+      const v = bone(s2, rule.bone, rule.prop === "rotation" ? "rotation" : "position", rule.space)[rule.prop === "y" ? 1 : 0];
+      if (rule.min !== void 0 && v < rule.min || rule.max !== void 0 && v > rule.max) bad++;
+    }
+    metrics[`condition:${slot.id}:${rule.bone}.${rule.prop}`] = { active: active2, bad };
+    if (bad || !active2 && rule.required) failures.push(`${slot.id} condition: ${bad} invalid visible samples, ${active2} active samples`);
+  }
+  for (const tr of cfg.transitions) {
+    for (const id of [tr.from, tr.to]) if (!doc.animations.some((a) => a.id === id)) throw new Error(`missing transition animation ${id}`);
+    const sink = { doc, pose: /* @__PURE__ */ new Map(), setPose(p) {
+      this.pose = p;
+    } }, state = new AnimationState(sink, { mix: tr.mix, missingAnimation: "throw" });
+    state.setBase(tr.from, { mix: 0 });
+    state.update(tr.fromTime);
+    let previous = evaluate(doc, sink.pose), previousPose = sink.pose, maxStep = 0;
+    state.play(tr.to);
+    const measure = () => {
+      const next = evaluate(doc, sink.pose);
+      for (const b of doc.bones) {
+        const a = previous.bones.get(b.id).world, c = next.bones.get(b.id).world;
+        const p = apply(a, b.length, 0), q = apply(c, b.length, 0);
+        maxStep = Math.max(maxStep, Math.hypot(c.tx - a.tx, c.ty - a.ty), Math.hypot(q[0] - p[0], q[1] - p[1]));
+      }
+      for (const s2 of doc.slots) {
+        if (previous.attachment.get(s2.id)?.id !== next.attachment.get(s2.id)?.id) continue;
+        const before = slotOutline(doc, previousPose, s2.id, 1, previous), after = slotOutline(doc, sink.pose, s2.id, 1, next);
+        if (before && after && before.length === after.length) for (let i = 0; i < before.length; i++) maxStep = Math.max(maxStep, Math.hypot(after[i][0] - before[i][0], after[i][1] - before[i][1]));
+      }
+      previous = next;
+      previousPose = sink.pose;
+    };
+    measure();
+    const count = Math.ceil(tr.duration * cfg.fps);
+    for (let i = 0; i < count; i++) {
+      state.update(1 / cfg.fps);
+      measure();
+    }
+    state.stop();
+    metrics[`transition:${tr.from}->${tr.to}`] = { samples: count + 1, maxStep, mix: tr.mix };
+    if (maxStep > tr.maxStep) failures.push(`transition ${tr.from}->${tr.to}: step ${maxStep} > ${tr.maxStep}`);
+  }
+  return { pass: failures.length === 0, animation: animation.id, fps: cfg.fps, interval: dt, expected: n + 1, inspected: frames.length, metrics, failures };
+}
+
+// src/rig-api.ts
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/rig-motion.ts
+var wrap2 = (x) => ((x + 180) % 360 + 360) % 360 - 180;
+var mesh = (doc, id) => {
+  const a = doc.attachments.find((a2) => a2.id === id);
+  if (a?.type !== "mesh") throw new Error(`expected mesh "${id}"`);
+  return a;
+};
+function skin(doc, a, weights) {
+  const skel = evaluate(doc, /* @__PURE__ */ new Map()), world = attachmentWorldVertices(skel, a.slot, a);
+  return weights.map((list, i) => {
+    const sum = [...list.values()].reduce((a2, b) => a2 + b, 0);
+    if (!(sum > 0)) throw new Error(`vertex ${i}: weights sum to zero`);
+    return [...list].filter(([, w]) => w > 1e-9).map(([bone, w]) => {
+      const b = skel.bones.get(bone);
+      if (!b) throw new Error(`unknown weight bone "${bone}"`);
+      const [x, y] = apply(invert(b.world), world[i * 2], world[i * 2 + 1]);
+      return { bone, x, y, w: w / sum };
+    });
+  });
+}
+function gradientWeights(doc, id, bones) {
+  const a = mesh(doc, id), skel = evaluate(doc, /* @__PURE__ */ new Map());
+  if (bones.length < 2 || new Set(bones).size !== bones.length) throw new Error("gradient needs at least two distinct bones");
+  const points = bones.map((id2) => {
+    const b = skel.bones.get(id2);
+    if (!b) throw new Error(`unknown bone "${id2}"`);
+    return [b.world.tx, b.world.ty];
+  });
+  const world = attachmentWorldVertices(skel, a.slot, a), weights = [];
+  for (let v = 0; v < world.length; v += 2) {
+    let best = Infinity, segment = 0, u = 0;
+    for (let i = 0; i < points.length - 1; i++) {
+      const [x, y] = points[i], dx = points[i + 1][0] - x, dy = points[i + 1][1] - y, l2 = dx * dx + dy * dy;
+      if (l2 < 1e-12) throw new Error("gradient chain contains coincident joints");
+      const t = Math.max(0, Math.min(1, ((world[v] - x) * dx + (world[v + 1] - y) * dy) / l2));
+      const d = (world[v] - x - t * dx) ** 2 + (world[v + 1] - y - t * dy) ** 2;
+      if (d < best) {
+        best = d;
+        segment = i;
+        u = t;
+      }
+    }
+    weights.push(/* @__PURE__ */ new Map([[bones[segment], 1 - u], [bones[segment + 1], u]]));
+  }
+  return setWeights(doc, id, skin(doc, a, weights)).doc;
+}
+function smoothWeights(doc, id, iterations = 3, strength = 0.5, locked = []) {
+  const a = mesh(doc, id);
+  if (!a.weights) throw new Error("skin the mesh before smoothing weights");
+  if (!Number.isInteger(iterations) || iterations < 1 || iterations > 100 || strength < 0 || strength > 1) throw new Error("invalid smoothing options");
+  const fixed = new Set(locked), neighbours = a.weights.map(() => /* @__PURE__ */ new Set());
+  for (const v of fixed) if (!Number.isInteger(v) || v < 0 || v >= neighbours.length) throw new Error(`invalid locked vertex ${v}`);
+  for (let i = 0; i < a.triangles.length; i += 3) for (const v of a.triangles.slice(i, i + 3)) for (const n of a.triangles.slice(i, i + 3)) if (v !== n) neighbours[v].add(n);
+  let w = a.weights.map((list) => new Map(list.map((i) => [i.bone, i.w])));
+  for (let iter = 0; iter < iterations; iter++) w = w.map((own, i) => {
+    if (fixed.has(i) || !neighbours[i].size) return own;
+    const next = new Map([...own].map(([b, v]) => [b, v * (1 - strength)]));
+    for (const n of neighbours[i]) for (const [b, v] of w[n]) next.set(b, (next.get(b) ?? 0) + strength * v / neighbours[i].size);
+    return next;
+  });
+  return setWeights(doc, id, skin(doc, a, w)).doc;
+}
+function pinWeights(doc, id, bone, vertices, region) {
+  const a = mesh(doc, id), skel = evaluate(doc, /* @__PURE__ */ new Map()), world = attachmentWorldVertices(skel, a.slot, a);
+  if (!skel.bones.has(bone)) throw new Error(`unknown bone "${bone}"`);
+  if (!vertices?.length && !region) throw new Error("select vertices or a document-space region");
+  const selected = new Set(vertices);
+  for (const v of selected) if (!Number.isInteger(v) || v < 0 || v >= world.length / 2) throw new Error(`invalid vertex ${v}`);
+  const host = doc.slots.find((s2) => s2.id === a.slot).bone;
+  let count = 0;
+  const w = Array.from({ length: world.length / 2 }, (_, i) => {
+    const x = world[i * 2], y = world[i * 2 + 1];
+    const inside = region && x >= region[0] && y >= region[1] && x <= region[0] + region[2] && y <= region[1] + region[3];
+    if (selected.has(i) || inside) {
+      count++;
+      return /* @__PURE__ */ new Map([[bone, 1]]);
+    }
+    return new Map(a.weights?.[i].map((inf) => [inf.bone, inf.w]) ?? [[host, 1]]);
+  });
+  if (!count) throw new Error("selection contains no mesh vertices");
+  return setWeights(doc, id, skin(doc, a, w)).doc;
+}
+function attachToBone(doc, animation, bone, target, t) {
+  const anim = doc.animations.find((a) => a.id === animation);
+  if (!anim || t < 0 || t > anim.duration) throw new Error("attach requires an existing animation and time within its duration");
+  const skel = evaluate(doc, poseOf(anim, t)), from = skel.bones.get(bone)?.world, to = skel.bones.get(target)?.world;
+  if (!from || !to || bone === target) throw new Error("attach needs distinct existing bones");
+  for (let b = doc.bones.find((b2) => b2.id === target); b; b = doc.bones.find((x2) => x2.id === b.parent)) if (b.id === bone) throw new Error("cannot attach to a descendant");
+  if (Math.abs(to.a * to.d - to.b * to.c) < 1e-10) throw new Error("cannot attach to a singular target");
+  const [x, y] = apply(invert(to), from.tx, from.ty);
+  const id = `attach_${bone}_${target}`;
+  const offset = {
+    x,
+    y,
+    rotation: wrap2(rotationOf(from) - rotationOf(to)),
+    scaleX: Math.hypot(from.a, from.b) - Math.hypot(to.a, to.b),
+    scaleY: Math.hypot(from.c, from.d) - Math.hypot(to.c, to.d),
+    shearY: wrap2((Math.atan2(from.d, from.c) - Math.atan2(from.b, from.a) - Math.atan2(to.d, to.c) + Math.atan2(to.b, to.a)) * 180 / Math.PI)
+  };
+  const order = Math.max(0, ...doc.ik.map((c) => c.order), ...doc.transform.map((c) => c.order), ...doc.path.map((c) => c.order)) + 1;
+  let next = setConstraint(doc, "transform", id, { bones: [bone], target, order, ...offset, mixX: 0, mixY: 0, mixRotate: 0, mixScaleX: 0, mixScaleY: 0, mixShearY: 0 });
+  for (const c of next.transform.filter((c2) => c2.id.startsWith(`attach_${bone}_`) && c2.bones.length === 1 && c2.bones[0] === bone)) {
+    for (const prop of ["mixX", "mixY", "mixRotate", "mixScaleX", "mixScaleY", "mixShearY"]) {
+      const has = anim.tracks.some((tr) => tr.target === "transform" && tr.id === c.id && tr.prop === prop);
+      const keys = [...!has && t > 0 ? [{ t: 0, v: 0, ease: "step" }] : [], { t, v: c.id === id ? 1 : 0, ease: "step" }];
+      next = setKeys(next, animation, { target: "transform", id: c.id, prop }, keys, void 0, { merge: true });
+    }
+  }
+  for (const [prop, v] of Object.entries(offset)) next = setKeys(next, animation, { target: "transform", id, prop }, [{ t, v, ease: "step" }], void 0, { merge: true });
+  return next;
+}
+function bakeSecondary(doc, animation, opts) {
+  const anim = doc.animations.find((a) => a.id === animation);
+  if (!anim) throw new Error(`unknown animation "${animation}"`);
+  const fps = opts.fps ?? 60, hz = opts.frequency ?? 2.5, damping = opts.damping ?? 0.65, gain = opts.gain ?? 0.2, maxAngle = opts.maxAngle ?? 30;
+  if (fps <= 0 || hz <= 0 || damping <= 0 || maxAngle <= 0 || !opts.bones.length) throw new Error("invalid spring parameters");
+  if (!doc.bones.some((b) => b.id === opts.driver) || opts.bones.includes(opts.driver)) throw new Error("driver must exist and be outside the secondary chain");
+  if (new Set(opts.bones).size !== opts.bones.length) throw new Error("secondary bones must be distinct");
+  for (let b = doc.bones.find((b2) => b2.id === opts.driver); b; b = doc.bones.find((x) => x.id === b.parent)) {
+    if (opts.bones.includes(b.id)) throw new Error("secondary bones cannot be ancestors of the driver");
+  }
+  const n = Math.max(2, Math.ceil(anim.duration * fps)), dt = anim.duration / n;
+  const base = { ...anim, tracks: anim.tracks.filter((t) => !(t.target === "bone" && opts.bones.includes(t.id) && t.prop === "rotation")) };
+  const angular = (opts.driverProp ?? "rotation") === "rotation";
+  const angles = Array.from({ length: n + 1 }, (_, i) => {
+    const world = evaluate(doc, poseOf(base, dt * i)).bones.get(opts.driver).world;
+    return angular ? rotationOf(world) : opts.driverProp === "x" ? world.tx : world.ty;
+  });
+  const seam = angles[n] - angles[0];
+  if (anim.loop && Math.abs(angular ? wrap2(seam) : seam) > 1e-3) throw new Error("loop driver must return to its starting world pose before baking");
+  let next = doc;
+  for (let bi = 0; bi < opts.bones.length; bi++) {
+    const bone = doc.bones.find((b) => b.id === opts.bones[bi]);
+    if (!bone) throw new Error(`unknown secondary bone "${opts.bones[bi]}"`);
+    const omega = 2 * Math.PI * hz / (1 + bi * 0.25), sub = Math.max(1, Math.ceil(dt * Math.max(240, omega * 12))), h = dt / sub;
+    let x = 0, velocity = 0, samples = [];
+    const cycle = () => {
+      samples = [x];
+      for (let i = 1; i <= n; i++) {
+        const difference = angles[i] - angles[i - 1];
+        const drive = (angular ? wrap2(difference) : difference) / dt;
+        for (let j2 = 0; j2 < sub; j2++) {
+          velocity += (-omega * omega * x - 2 * damping * omega * velocity - gain * omega * drive) * h;
+          x += velocity * h;
+          if (Math.abs(x) > maxAngle) {
+            x = Math.sign(x) * maxAngle;
+            velocity = 0;
+          }
+        }
+        samples.push(x);
+      }
+    };
+    if (anim.loop) {
+      let converged = false;
+      for (let i = 0; i < 200; i++) {
+        const oldX = x, oldV = velocity;
+        cycle();
+        if (Math.abs(x - oldX) < 1e-7 && Math.abs(velocity - oldV) < 1e-7) {
+          converged = true;
+          break;
+        }
+      }
+      if (!converged) throw new Error("spring loop did not converge; increase damping or duration");
+      samples[n] = samples[0];
+    } else cycle();
+    const origin = anim.loop ? samples[0] : 0;
+    const amplitude = Math.max(...samples.map((v) => Math.abs(v - origin)));
+    const scale = Math.min(1, maxAngle / Math.max(amplitude, 1e-12));
+    next = setKeys(next, animation, { target: "bone", id: bone.id, prop: "rotation", interpolation: "pchip" }, samples.map((v, i) => ({ t: i * dt, v: bone.transform.rotation + (v - origin) * scale, ease: "linear" })), anim.duration);
+  }
+  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) {
   const handler = run;
-  tools.push({ name, description, input: z2.object(input).strict(), run: (args2) => typeof args2.path === "string" ? withRigQueue(args2.path, () => handler(args2)) : handler(args2) });
+  tools.push({ name, description, input: z3.object(input).strict(), run: (args2) => typeof args2.path === "string" ? withRigQueue(args2.path, () => handler(args2)) : handler(args2) });
 }
 async function callTool(name, args2) {
   const t = tools.find((t2) => t2.name === name);
@@ -4394,24 +5423,24 @@ async function callTool(name, args2) {
 var closeTools = () => closePreview();
 var text = (s2, doc) => ({ text: s2, doc });
 var fail = (e) => ({ text: `ERROR: ${e instanceof Error ? e.message : String(e)}`, isError: true });
-var Path = z2.string().describe("path to rig.json; assets are resolved relative to its directory");
-var Library = z2.string().optional().describe("template library JSON; default presets.json next to rig.json");
+var Path = z3.string().describe("path to rig.json; assets are resolved relative to its directory");
+var Library = z3.string().optional().describe("template library JSON; default presets.json next to rig.json");
 async function load(path) {
-  return RigDocument.parse(JSON.parse(await readFile8(path, "utf8")));
+  return RigDocument.parse(JSON.parse(await readFile9(path, "utf8")));
 }
 var save = (path, doc) => saveJson(path, doc);
 var exists2 = (p) => stat2(p).then(() => true, () => false);
-var resolveFrom = (rigPath, p) => isAbsolute(p) ? p : join7(dirname6(rigPath), p);
-var srcFor = (rigPath, file) => relative2(dirname6(rigPath), file).split("\\").join("/");
-var libraryFor = (rigPath, lib) => lib ? resolveFrom(rigPath, lib) : join7(dirname6(rigPath), "presets.json");
+var resolveFrom = (rigPath, p) => isAbsolute(p) ? p : join9(dirname8(rigPath), p);
+var srcFor = (rigPath, file) => relative2(dirname8(rigPath), file).split("\\").join("/");
+var libraryFor = (rigPath, lib) => lib ? resolveFrom(rigPath, lib) : join9(dirname8(rigPath), "presets.json");
 async function pngInfo(rigPath, file) {
   const abs = resolveFrom(rigPath, file);
-  const [width, height] = pngSize(await readFile8(abs));
+  const [width, height] = pngSize(await readFile9(abs));
   return { abs, width, height, src: srcFor(rigPath, abs) };
 }
 async function mutate(path, op, summary = false) {
   try {
-    const raw = await readFile8(path, "utf8");
+    const raw = await readFile9(path, "utf8");
     const prev = RigDocument.parse(JSON.parse(raw));
     const next = parse(await op(prev));
     await pushHistory(path, raw);
@@ -4425,7 +5454,7 @@ changed:${changes.length ? "\n  " + changes.join("\n  ") : " nothing"}`, next);
   }
 }
 async function create(path, doc) {
-  if (await exists2(path)) await pushHistory(path, await readFile8(path, "utf8"));
+  if (await exists2(path)) await pushHistory(path, await readFile9(path, "utf8"));
   const saved = parse(doc);
   await save(path, saved);
   return text(describe(saved), saved);
@@ -4437,18 +5466,91 @@ 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 = { target: z2.enum(["bone", "slot", "deform", "ik", "transform", "path", "drawOrder"]), id: z2.string(), prop: z2.string() };
-var KeyIn = z2.object({
-  t: z2.number().describe("seconds"),
-  v: z2.union([z2.number(), z2.string(), z2.null(), z2.array(z2.number()), z2.array(z2.string())]),
-  ease: Ease.optional().describe("into the next key: linear|step|ease_in|ease_out|ease_in_out|back_out|elastic_out|{bezier:[x1,y1,x2,y2]}; default ease_in_out")
+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())]),
+  ease: Ease.optional().describe("into the next key: linear|step|ease_in|ease_out|ease_in_out|back_out|elastic_out|{bezier:[x1,y1,x2,y2]}; default ease_in_out; minimum_jerk for a rest-to-rest segment")
 });
 var roundKey = (k) => Array.isArray(k.v) && k.v.every((x) => typeof x === "number") ? { ...k, v: k.v.map(round6) } : k;
 var KEY_DOC = "Keys are {t, v, ease?}. Bone values are ABSOLUTE local-transform values, not offsets (rest x=4 \u2192 key v=0 moves it 4px); deform values are relative (0 = rest). bone: x|y|rotation|scaleX|scaleY|shearX|shearY; slot: alpha|attachment(asset id or null)|z; deform (3\xD73 mesh on the slot's image): bulge|bend|sway|squash (fractions of the image size, |v|\u22640.9/1) or p<row><col>x|y (px, rows/cols 0..2 top-left first). Some values are arrays: deform `vertices` keys are number arrays (2\xB7n offsets, or 2\xB7\u03A3influences for weighted meshes); drawOrder keys are slot-id arrays; slot color keys are [r,g,b,a].";
 tool(
   "rig_create",
   "Create a new empty rig document with a root bone at bottom-center.",
-  { path: Path, name: z2.string(), width: z2.number().int(), height: z2.number().int(), notes: z2.string().optional().describe("style anchor + what is intentionally missing; reused by rig_layer_prompt") },
+  { path: Path, name: z3.string(), width: z3.number().int(), height: z3.number().int(), notes: z3.string().optional().describe("style anchor + what is intentionally missing; reused by rig_layer_prompt") },
   async ({ path, name, width, height, notes }) => {
     try {
       return await create(path, createDoc(name, width, height, notes));
@@ -4460,7 +5562,7 @@ tool(
 tool(
   "rig_create_symbol",
   "Create a rig from ONE image (a slot symbol): canvas = image + margin, root at the image's bottom centre, slot pivot (0.5, 1). Then apply symbol_idle / symbol_win / anticipation_shake / dim presets.",
-  { path: Path, image: z2.string().describe("PNG path, absolute or relative to rig.json dir"), name: z2.string().optional(), margin: z2.number().default(0.15).describe("fraction of the image size on every side, room for bounces"), notes: z2.string().optional() },
+  { path: Path, image: z3.string().describe("PNG path, absolute or relative to rig.json dir"), name: z3.string().optional(), margin: z3.number().default(0.15).describe("fraction of the image size on every side, room for bounces"), notes: z3.string().optional() },
   async ({ path, image, name, margin, notes }) => {
     try {
       const { width, height, src } = await pngInfo(path, image);
@@ -4470,22 +5572,22 @@ tool(
     }
   }
 );
-var ReferenceIn = z2.object({
-  src: z2.string().describe("PNG next to rig.json (relative path)"),
-  opacity: z2.number().min(0).max(1).optional(),
-  x: z2.number().optional(),
-  y: z2.number().optional(),
-  scale: z2.number().positive().optional()
+var ReferenceIn = z3.object({
+  src: z3.string().describe("PNG next to rig.json (relative path)"),
+  opacity: z3.number().min(0).max(1).optional(),
+  x: z3.number().optional(),
+  y: z3.number().optional(),
+  scale: z3.number().positive().optional()
 }).strict();
 tool(
   "rig_set_meta",
   "Patch the document's meta: name, canvas width/height (moves nothing \u2014 only the bounds change), notes, and the editor's reference underlay `reference {src, opacity, x, y, scale}` \u2014 a PNG next to rig.json drawn under the canvas to fit parts against; runtime, preview and export ignore it; null removes it.",
   {
     path: Path,
-    name: z2.string().optional(),
-    width: z2.number().int().positive().optional(),
-    height: z2.number().int().positive().optional(),
-    notes: z2.string().optional(),
+    name: z3.string().optional(),
+    width: z3.number().int().positive().optional(),
+    height: z3.number().int().positive().optional(),
+    notes: z3.string().optional(),
     reference: ReferenceIn.nullable().optional()
   },
   async ({ path, ...patch }) => mutate(path, (d) => setMeta(d, patch))
@@ -4493,7 +5595,7 @@ tool(
 tool(
   "rig_get",
   "Read a rig. Compact summary by default; verbose=true adds slot pivot/offset and every track with key counts and value ranges (no asset prompts); full=true returns the JSON.",
-  { path: Path, verbose: z2.boolean().default(false), full: z2.boolean().default(false) },
+  { path: Path, verbose: z3.boolean().default(false), full: z3.boolean().default(false) },
   async ({ path, verbose, full }) => {
     try {
       const d = await load(path);
@@ -4506,7 +5608,7 @@ tool(
 tool(
   "rig_get_attachment",
   "ONE attachment, in full: the exact `vertices` / `weights` / `uvs` / `triangles` arrays it stores. This is what the raw forms of rig_set_path_attachment and rig_set_mesh want \u2014 they edit a shape in place instead of rebuilding it, and to edit `weights` you have to start from the `weights` that are there. The FIRST LINE is a summary (kind, slot, vertex/anchor counts, skinning, the length a deform `vertices` key must have); everything after the first newline is the attachment object as JSON, ready to hand straight back. rig_get full=true returns the same arrays inside the whole document, which is 3.3 MB on a Spine import against a few KB here.",
-  { path: Path, id: z2.string().describe("attachment id (rig_get lists them per slot with verbose=true)") },
+  { path: Path, id: z3.string().describe("attachment id (rig_get lists them per slot with verbose=true)") },
   async ({ path, id }) => {
     try {
       const d = await load(path);
@@ -4524,10 +5626,10 @@ tool(
   "Where every bone actually IS at one moment: world x, y, angle (degrees) and axis lengths, with the bone's own local x, y and rotation, plus each slot's shown attachment and world bounding box. Constraints are applied, so this is what the runtime draws, not what the document stores. Without `animation` it reports the rest pose, and `t` is then an error rather than a number that does nothing. A `t` past the animation's duration is clamped to the end, and the summary line says so. `bones` and `slots` narrow the report \u2014 pass them on a large rig, where the whole report runs to tens of KB. Use it to check an edit landed where you meant instead of reading it off a preview image.",
   {
     path: Path,
-    animation: z2.string().optional(),
-    t: z2.number().min(0).optional(),
-    bones: z2.array(z2.string()).optional(),
-    slots: z2.array(z2.string()).optional()
+    animation: z3.string().optional(),
+    t: z3.number().min(0).optional(),
+    bones: z3.array(z3.string()).optional(),
+    slots: z3.array(z3.string()).optional()
   },
   async ({ path, ...opts }) => {
     try {
@@ -4556,11 +5658,11 @@ tool(
 );
 tool(
   "rig_check",
-  "Cheap self-critique without rendering: out_of_canvas (slot leaves the canvas, worst time), static_track, loop_seam, deform_flip (lattice folds over itself \u2014 an error), mesh_fold (a skinned/deformed mesh folds over itself: error when \u2265 5 % of the mesh folds, warning below \u2014 a dense mesh bent hard at a joint pinches the odd hairline triangle), weights_sum (skinned mesh vertex weights not summing to 1), patch_offset (a slot sits away from its asset's source bbox), rest_overlap, unused_asset, never_visible, and for constraints: constraint_dead (every mix is 0 at rest and no track lifts one \u2014 the solver skips it), constraint_cycle (the target is a bone the constraint drives, or hangs off one: it reads what it writes \u2014 an error), ik_unreachable (the target sits beyond the chain's reach for over 20 % of an animation, so the limb hangs straight), path_missing (a path constraint whose target slot never shows a path attachment \u2014 an error). Findings are sorted by severity. Run it before spending vision tokens on a preview.",
-  { path: Path, animation: z2.string().optional().describe("limit to one animation (rest pose is always checked)") },
-  async ({ path, animation }) => {
+  "Cheap self-critique without rendering: out_of_canvas (slot leaves the canvas, worst time), static_track, loop_seam, deform_flip (lattice folds over itself \u2014 an error), mesh_fold (a skinned/deformed mesh folds over itself: error when \u2265 5 % of the mesh folds, warning below \u2014 a dense mesh bent hard at a joint pinches the odd hairline triangle), weights_sum (skinned mesh vertex weights not summing to 1), patch_offset (a slot sits away from its asset's source bbox), rest_overlap, unused_asset, never_visible, and for constraints: constraint_dead (every mix is 0 at rest and no track lifts one \u2014 the solver skips it), constraint_cycle (the target is a bone the constraint drives, or hangs off one: it reads what it writes \u2014 an error), ik_unreachable (the target sits beyond the chain's reach for over 20 % of an animation, so the limb hangs straight), path_missing (a path constraint whose target slot never shows a path attachment \u2014 an error). Motion diagnostics also cover pass_key_stop, velocity_jump, acceleration_jump, loop_velocity and constraint_order; provide secondaryBones, frontOf slot pairs and named attachment UV landmarks for brief-specific frozen-motion, ordering and swap-registration checks. Findings are sorted by severity. Run it before spending vision tokens on a preview.",
+  { path: Path, animation: z3.string().optional().describe("limit to one animation (rest pose is always checked)"), fps: z3.number().positive().optional(), deformFps: z3.number().positive().optional(), secondaryBones: z3.array(z3.string()).optional(), frontOf: z3.array(z3.tuple([z3.string(), z3.string()])).optional(), landmarks: z3.record(z3.record(z3.tuple([z3.number(), z3.number()]))).optional(), landmarkTolerance: z3.number().nonnegative().optional() },
+  async ({ path, ...opts }) => {
     try {
-      return text(summarize(checkRig(await load(path), { animation }), 100));
+      return text(summarize(checkRig(await load(path), opts), 100));
     } catch (e) {
       return fail(e);
     }
@@ -4571,12 +5673,12 @@ tool(
   "Import a Spine project (skeleton .json 3.8/4.x + .atlas + page image) as a new rig: bones, slots, region/mesh/path attachments with weights, IK / transform / path constraints and every animation (deform, draw order, colors), converted to this document's y-down space. The atlas may be plain or base64 text; a KTX2 page is transcoded to PNG next to rig.json. Then use rig_get / rig_render_preview / rig_check as with any rig.",
   {
     path: Path,
-    json: z2.string().describe("Spine skeleton .json, absolute or relative to rig.json dir"),
-    atlas: z2.string().optional().describe("atlas file; default: <json>.atlas or <json>.atlas.txt"),
-    image: z2.string().optional().describe("atlas page image (.png or .ktx2); default: the page named in the atlas, next to it"),
-    name: z2.string().optional().describe("default: the json file name"),
-    margin: z2.number().optional().describe("canvas margin around the skeleton bounds, px"),
-    notes: z2.string().optional()
+    json: z3.string().describe("Spine skeleton .json, absolute or relative to rig.json dir"),
+    atlas: z3.string().optional().describe("atlas file; default: <json>.atlas or <json>.atlas.txt"),
+    image: z3.string().optional().describe("atlas page image (.png or .ktx2); default: the page named in the atlas, next to it"),
+    name: z3.string().optional().describe("default: the json file name"),
+    margin: z3.number().optional().describe("canvas margin around the skeleton bounds, px"),
+    notes: z3.string().optional()
   },
   async ({ path, json, atlas, image, name, margin, notes }) => {
     try {
@@ -4594,13 +5696,13 @@ warnings:
 tool(
   "rig_import_layers",
   "Import PNG layers from a directory as assets + slots + bones. Uses layers.json sidecar if present (id, role, parent, z, bbox, joint, swap, bone, slot), else filename convention `03_arm_l.png` \u2192 z=3, id=arm_l, role from known names. Bone hierarchy is inferred from roles (head\u2192neck\u2192torso\u2192hips\u2192root, arms\u2192torso, legs\u2192hips). `swap: true` = patch (closed eyes, mouth) as a hidden slot on the parent's bone; several swap layers with the same `slot` share one slot; `bone` = attach to an existing bone without creating one.",
-  { path: Path, layersDir: z2.string().describe("absolute dir, or relative to rig.json dir"), relPrefix: z2.string().default("layers").describe("how asset.src refers to the dir, relative to rig.json") },
+  { path: Path, layersDir: z3.string().describe("absolute dir, or relative to rig.json dir"), relPrefix: z3.string().default("layers").describe("how asset.src refers to the dir, relative to rig.json") },
   async ({ path, layersDir, relPrefix }) => mutate(path, (d) => importLayers(d, resolveFrom(path, layersDir), relPrefix), true)
 );
 tool(
   "rig_replace_asset",
   "Swap one layer's PNG (e.g. a regenerated part) without rebuilding the rig. Pivots are fractions, so the slot keeps working; the image should keep the same silhouette registration.",
-  { path: Path, id: z2.string(), file: z2.string().describe("new PNG, absolute or relative to rig.json dir"), prompt: z2.string().optional().describe("provenance: how it was generated") },
+  { path: Path, id: z3.string(), file: z3.string().describe("new PNG, absolute or relative to rig.json dir"), prompt: z3.string().optional().describe("provenance: how it was generated") },
   async ({ path, id, file, prompt }) => mutate(path, async (d) => {
     const { width, height, src } = await pngInfo(path, file);
     return replaceAsset(d, id, { src, width, height, prompt, inpainted: true });
@@ -4609,27 +5711,27 @@ tool(
 tool(
   "rig_layer_prompt",
   "Build a parts-first image-generation prompt for one layer from its provenance (asset.origin), the rig's style notes and its bone context. Generate the image with your image tool, then rig_replace_asset.",
-  { path: Path, id: z2.string() },
-  async ({ path, id }) => {
+  { path: Path, method: z3.enum(["part", "repair"]).default("part"), removed: z3.array(z3.string()).optional(), id: z3.string() },
+  async ({ path, id, method, removed }) => {
     try {
-      return text(layerPrompt(await load(path), id));
+      return text(layerPrompt(await load(path), id, { method, removed }));
     } catch (e) {
       return fail(e);
     }
   }
 );
-var Frame = z2.tuple([z2.number().int(), z2.number().int(), z2.number().int(), z2.number().int()]).describe("[x, y, w, h] rectangle in the source image's pixels");
-var OriginIn = z2.object({ sourceImage: z2.string().optional(), bbox: Frame.optional(), inpainted: z2.boolean().default(false), prompt: z2.string().optional() }).strict();
+var Frame = z3.tuple([z3.number().int(), z3.number().int(), z3.number().int(), z3.number().int()]).describe("[x, y, w, h] rectangle in the source image's pixels");
+var OriginIn = z3.object({ bboxSpace: z3.enum(["source", "document"]).optional(), sourceImage: z3.string().optional(), bbox: Frame.optional(), inpainted: z3.boolean().default(false), prompt: z3.string().optional() }).strict();
 tool(
   "rig_set_asset",
   "Create or patch an asset. `src` = a PNG relative to rig.json (needed to create); `frame` = one rectangle of that PNG (a part split off a sheet \u2014 the runtime, preview, export and editor all cut it at draw time, no crop file); without `frame` the asset is the whole image. Re-framing an asset that regions show keeps the source pixel under each image centre where it is drawn; a mesh keeps its uvs and is named so you can re-trace it. Place it with rig_place_asset.",
   {
     path: Path,
-    id: z2.string(),
-    src: z2.string().optional(),
+    id: z3.string(),
+    src: z3.string().optional(),
     frame: Frame.nullable().optional().describe("null = the whole image again"),
-    width: z2.number().int().positive().optional(),
-    height: z2.number().int().positive().optional(),
+    width: z3.number().int().positive().optional(),
+    height: z3.number().int().positive().optional(),
     origin: OriginIn.optional()
   },
   async ({ path, id, src, ...patch }) => mutateWith(path, async (d, say) => {
@@ -4647,19 +5749,19 @@ tool(
 tool(
   "rig_remove_asset",
   "Remove an asset nothing shows any more (refused, with the list, while an attachment still uses it).",
-  { path: Path, id: z2.string() },
+  { path: Path, id: z3.string() },
   async ({ path, id }) => mutate(path, (d) => removeAsset(d, id))
 );
 tool(
   "rig_place_asset",
   "Put an asset on a bone in ONE call: a slot (`slot` or the asset's id; created on `bone` when missing, an existing slot keeps its bone), a region attachment named like the asset with its centre at the DOCUMENT point (x, y), and the slot showing it. z = max + 1 unless given. Then rotate/scale with rig_set_attachment.",
-  { path: Path, asset: z2.string(), bone: z2.string(), x: z2.number(), y: z2.number(), slot: z2.string().optional(), z: z2.number().int().optional() },
+  { path: Path, asset: z3.string(), bone: z3.string(), x: z3.number(), y: z3.number(), slot: z3.string().optional(), z: z3.number().int().optional() },
   async ({ path, ...p }) => mutate(path, (d) => placeAsset(d, p), true)
 );
 tool(
   "rig_undo",
   "Restore the rig as it was `steps` mutations ago (every mutation snapshots the previous file into .rig-history/ next to rig.json).",
-  { path: Path, steps: z2.number().int().min(1).default(1) },
+  { path: Path, steps: z3.number().int().min(1).default(1) },
   async ({ path, steps }) => {
     try {
       const doc = parse(JSON.parse(await undo(path, steps)));
@@ -4688,13 +5790,13 @@ tool(
 tool(
   "rig_diff",
   "Structural difference between the current rig and the snapshot `steps` mutations ago: bones/slots/assets added, removed, changed; tracks with key counts and value ranges; preset params.",
-  { path: Path, steps: z2.number().int().min(1).default(1) },
+  { path: Path, steps: z3.number().int().min(1).default(1) },
   async ({ path, steps }) => {
     try {
       const history = await listHistory(path);
       if (!history.length) return text("no history for this rig");
       if (steps > history.length) return text(`only ${history.length} snapshot${history.length === 1 ? "" : "s"} available`);
-      const old = RigDocument.parse(JSON.parse(await readFile8(history[history.length - steps], "utf8")));
+      const old = RigDocument.parse(JSON.parse(await readFile9(history[history.length - steps], "utf8")));
       const lines = diffDocs(old, await load(path));
       return text(lines.length ? lines.join("\n") : "no differences");
     } catch (e) {
@@ -4702,19 +5804,19 @@ tool(
     }
   }
 );
-var TransformPatch = z2.object({ x: z2.number(), y: z2.number(), rotation: z2.number(), scaleX: z2.number(), scaleY: z2.number(), shearX: z2.number(), shearY: z2.number() }).partial();
+var TransformPatch = z3.object({ x: z3.number(), y: z3.number(), rotation: z3.number(), scaleX: z3.number(), scaleY: z3.number(), shearX: z3.number(), shearY: z3.number() }).partial();
 var BoneFields = {
-  parent: z2.string().optional(),
-  role: z2.string().optional(),
-  length: z2.number().optional().describe("px to the far joint; editor rotation handle, weight_shift leg length"),
-  inherit: z2.enum(["normal", "onlyTranslation", "noRotationOrReflection", "noScale", "noScaleOrReflection"]).optional(),
-  color: z2.string().optional().describe("editor colour"),
+  parent: z3.string().optional(),
+  role: z3.string().optional(),
+  length: z3.number().optional().describe("px to the far joint; editor rotation handle, weight_shift leg length"),
+  inherit: z3.enum(["normal", "onlyTranslation", "noRotationOrReflection", "noScale", "noScaleOrReflection"]).optional(),
+  color: z3.string().optional().describe("editor colour"),
   transform: TransformPatch.optional()
 };
 tool(
   "rig_add_bone",
   "Add a bone. transform is LOCAL to parent (px, degrees CW). Omit parent \u2192 root. `bind` moves those slots onto the new bone without moving their images (the editor's B tool with a part selected).",
-  { path: Path, id: z2.string(), ...BoneFields, bind: z2.array(z2.string()).optional().describe("slot ids to re-bind onto the new bone, world placement kept") },
+  { path: Path, id: z3.string(), ...BoneFields, bind: z3.array(z3.string()).optional().describe("slot ids to re-bind onto the new bone, world placement kept") },
   async ({ path, bind, ...bone }) => mutateWith(path, (d, say) => {
     let next = addBone(d, bone);
     for (const s2 of bind ?? []) {
@@ -4728,13 +5830,13 @@ tool(
 tool(
   "rig_update_bone",
   "Patch bone fields (parent, role, length, inherit, color, transform \u2014 partial, merged). parent=null detaches the bone into a root of its own.",
-  { path: Path, id: z2.string(), ...BoneFields, parent: z2.string().nullable().optional().describe("new parent bone; null = make it a root bone (a rig may have several)") },
+  { path: Path, id: z3.string(), ...BoneFields, parent: z3.string().nullable().optional().describe("new parent bone; null = make it a root bone (a rig may have several)") },
   async ({ path, id, ...patch }) => mutate(path, (d) => updateBone(d, id, patch))
 );
 tool(
   "rig_remove_bone",
   "Remove a bone; children and slots re-parent to its parent.",
-  { path: Path, id: z2.string() },
+  { path: Path, id: z3.string() },
   async ({ path, id }) => mutateWith(path, (d, say) => {
     const parent = d.bones.find((b) => b.id === id)?.parent;
     const slots = d.slots.filter((s2) => s2.bone === id).map((s2) => s2.id);
@@ -4745,18 +5847,19 @@ tool(
 );
 tool(
   "rig_set_slot",
-  "Create or patch a slot (a draw layer on a bone). attachment = id of one of its attachments, null hides it (swap slots). blend=add for glow/fire layers painted on black; color is #rrggbbaa tint. Changing `bone` on an existing slot KEEPS its images where they are on the document (placements are re-expressed in the new bone's rest frame; weighted meshes need nothing).",
+  "Create or patch a slot (a draw layer on a bone). attachment = id of one of its attachments, null hides it (swap slots). blend=add for glow/fire layers painted on black; color is #rrggbbaa tint. clip names a closed path attachment used as a moving mask; null removes it. Changing `bone` on an existing slot KEEPS its images where they are on the document (placements are re-expressed in the new bone's rest frame; weighted meshes need nothing).",
   {
     path: Path,
-    id: z2.string(),
-    bone: z2.string().optional(),
-    attachment: z2.string().nullable().optional(),
-    z: z2.number().int().optional(),
-    alpha: z2.number().optional(),
-    blend: z2.enum(["normal", "add", "multiply", "screen"]).optional(),
-    color: z2.string().optional()
+    id: z3.string(),
+    bone: z3.string().optional(),
+    clip: z3.string().nullable().optional(),
+    attachment: z3.string().nullable().optional(),
+    z: z3.number().int().optional(),
+    alpha: z3.number().optional(),
+    blend: z3.enum(["normal", "add", "multiply", "screen"]).optional(),
+    color: z3.string().optional()
   },
-  async ({ path, attachment, bone, ...slot }) => mutateWith(path, (d, say) => {
+  async ({ path, attachment, bone, clip, ...slot }) => mutateWith(path, (d, say) => {
     let next = d;
     const cur = d.slots.find((s2) => s2.id === slot.id);
     if (cur && bone !== void 0 && bone !== cur.bone) {
@@ -4764,7 +5867,7 @@ tool(
       next = r.doc;
       if (r.approx > 0.01) say(`slot "${slot.id}" re-bound to "${bone}" approximately: a region corner moved ${r.approx} px (shear or non-uniform scale between the bones)`);
     }
-    return setSlot(next, { ...slot, ...bone !== void 0 ? { bone } : {}, ...attachment === void 0 ? {} : { attachment: attachment ?? void 0 } });
+    return setSlot(next, { ...slot, ...clip === void 0 ? {} : { clip: clip ?? void 0 }, ...bone !== void 0 ? { bone } : {}, ...attachment === void 0 ? {} : { attachment: attachment ?? void 0 } });
   })
 );
 tool(
@@ -4772,21 +5875,21 @@ tool(
   "Create or patch a REGION attachment: an image (asset) placed in a slot. x/y = the image CENTRE in the slot bone's space, rotation in degrees, scale; fields are merged. A slot can hold several attachments (swap states); set slot.attachment to show one. Meshes come from rig_mesh_from_image (trace this region's image) or rig_import_spine.",
   {
     path: Path,
-    id: z2.string(),
-    slot: z2.string().optional(),
-    asset: z2.string().optional(),
-    x: z2.number().optional(),
-    y: z2.number().optional(),
-    rotation: z2.number().optional(),
-    scaleX: z2.number().optional(),
-    scaleY: z2.number().optional(),
-    width: z2.number().optional(),
-    height: z2.number().optional()
+    id: z3.string(),
+    slot: z3.string().optional(),
+    asset: z3.string().optional(),
+    x: z3.number().optional(),
+    y: z3.number().optional(),
+    rotation: z3.number().optional(),
+    scaleX: z3.number().optional(),
+    scaleY: z3.number().optional(),
+    width: z3.number().optional(),
+    height: z3.number().optional()
   },
   async ({ path, ...att }) => mutate(path, (d) => setAttachment(d, att))
 );
-var Influence2 = z2.object({ bone: z2.string(), x: z2.number(), y: z2.number(), w: z2.number() }).describe("one influence: the vertex in that bone's local space and its weight");
-var WeightsIn = z2.array(z2.array(Influence2).min(1)).describe("one influence list per vertex, in uv order; weights of a list should sum to 1");
+var Influence2 = z3.object({ bone: z3.string(), x: z3.number(), y: z3.number(), w: z3.number() }).describe("one influence: the vertex in that bone's local space and its weight");
+var WeightsIn = z3.array(z3.array(Influence2).min(1)).describe("one influence list per vertex, in uv order; weights of a list should sum to 1");
 async function mutateWith(path, op, summary = false) {
   const lines = [];
   const res = await mutate(path, (d) => op(d, (l) => lines.push(l)), summary);
@@ -4801,14 +5904,15 @@ var meshOf = (doc, id) => {
 };
 tool(
   "rig_mesh_from_image",
-  "Turn a REGION attachment into a mesh traced from its PNG's alpha: the outline (pixels with alpha \u2265 threshold, simplified by tolerance px, pushed out by margin px) plus an interior grid every `spacing` px, Delaunay-triangulated. EVERY separate opaque island of the layer is meshed (a closed-eyes overlay is two strokes) \u2014 islands under 5% of the largest, and holes, are skipped; the answer says `islands: N` when there is more than one, and such a mesh reports hull 0. The mesh keeps the region's id, slot, asset and placement, so nothing moves; lattice deform tracks (bulge/bend/sway/squash/p<rc>) on it are dropped (they only apply to regions). Next: rig_auto_weights, then key deform `vertices`.",
+  "Turn a REGION attachment into a mesh traced from its PNG's alpha: the outline (pixels with alpha \u2265 threshold, simplified by tolerance px, pushed out by margin px) plus an interior grid every `spacing` px, Delaunay-triangulated. EVERY separate opaque island of the layer is meshed (a closed-eyes overlay is two strokes) \u2014 islands below minIslandRatio (default 5% of the largest), and holes, are skipped; the answer says `islands: N` when there is more than one, and such a mesh reports hull 0. The mesh keeps the region's id, slot, asset and placement, so nothing moves; lattice deform tracks (bulge/bend/sway/squash/p<rc>) on it are dropped (they only apply to regions). Next: rig_auto_weights, then key deform `vertices`.",
   {
     path: Path,
-    id: z2.string().describe("attachment id (a region)"),
-    spacing: z2.number().min(1).default(24).describe("interior vertex spacing in image px; smaller = denser mesh"),
-    tolerance: z2.number().nonnegative().default(2).describe("outline simplification in px; 0 keeps every pixel step"),
-    margin: z2.number().default(1).describe("px the outline is pushed outward, so the traced edge keeps the soft pixels"),
-    threshold: z2.number().int().min(1).max(255).default(8).describe("alpha value counted as opaque")
+    id: z3.string().describe("attachment id (a region)"),
+    spacing: z3.number().min(1).default(24).describe("interior vertex spacing in image px; smaller = denser mesh"),
+    tolerance: z3.number().nonnegative().default(2).describe("outline simplification in px; 0 keeps every pixel step"),
+    margin: z3.number().default(1).describe("px the outline is pushed outward, so the traced edge keeps the soft pixels"),
+    minIslandRatio: z3.number().min(0).max(1).default(0.05).describe("minimum island area relative to largest; 0 preserves small intentional fragments"),
+    threshold: z3.number().int().min(1).max(255).default(8).describe("alpha value counted as opaque")
   },
   async ({ path, id, ...opts }) => mutateWith(path, async (d, say) => {
     const att = d.attachments.find((a) => a.id === id);
@@ -4817,15 +5921,15 @@ tool(
     const asset = d.assets.find((a) => a.id === att.asset);
     if (!asset) throw new Error(`unknown asset "${att.asset}"`);
     if (asset.rotate || asset.trim) throw new Error(`asset "${asset.id}" is packed into an exported atlas (rotate/trim): run rig_mesh_from_image on the unpacked rig, not an atlas export`);
-    const png = await readFile8(resolveFrom(path, asset.src)).catch((e) => {
+    const png = await readFile9(resolveFrom(path, asset.src)).catch((e) => {
       throw new Error(`asset "${asset.id}": cannot read ${asset.src} (${e.code ?? e.message})`);
     });
     const { spacing, ...trace } = opts;
     const mask = alphaMaskFromPng(png, asset.frame);
     const islands = traceHulls(mask, trace);
-    const mesh = meshFromIslands(islands, att, asset, mask, spacing);
-    const { doc, droppedTracks } = convertToMesh(d, mesh);
-    say(`${id}=mesh(${mesh.uvs.length / 2}v, ${mesh.triangles.length / 3}t, hull ${mesh.hull}${islands.length > 1 ? `, islands: ${islands.length}` : ""})`);
+    const mesh2 = meshFromIslands(islands, att, asset, mask, spacing);
+    const { doc, droppedTracks } = convertToMesh(d, mesh2);
+    say(`${id}=mesh(${mesh2.uvs.length / 2}v, ${mesh2.triangles.length / 3}t, hull ${mesh2.hull}${islands.length > 1 ? `, islands: ${islands.length}` : ""})`);
     if (droppedTracks.length) say(`dropped lattice deform tracks: ${droppedTracks.join(", ")}`);
     return doc;
   })
@@ -4835,10 +5939,10 @@ tool(
   "Skin a mesh to bones by distance: each vertex takes the `maxInfluences` (default 2) nearest candidate bones, inverse-distance weighted and normalized to 1. Nothing is dropped for being far away, so a vertex far from every joint still blends its two nearest bones instead of snapping to one at weight 1. `radius` scales the falloff \u2014 weight `1 / (distance/radius + 1)\xB2` \u2014 in world px, default 1: a larger radius spreads influence across more bones, a smaller one binds each vertex more tightly to its nearest bone. There is no cutoff at any radius. Default `bones`, from the REST pose: the slot's bone, its parent and its direct children. Replaces the mesh's `vertices` with `weights`, so deform `vertices` keys on it are dropped (their length changes). Check the result with rig_render_preview.",
   {
     path: Path,
-    id: z2.string().describe("mesh attachment id"),
-    bones: z2.array(z2.string()).min(1).optional().describe("candidate bones; default: the slot's bone + its parent + its children"),
-    radius: z2.number().positive().optional().describe("falloff scale in world px, default 1; larger spreads influence across more bones, smaller binds tighter to the nearest one; no cutoff"),
-    maxInfluences: z2.number().int().min(1).default(2).describe("bones per vertex")
+    id: z3.string().describe("mesh attachment id"),
+    bones: z3.array(z3.string()).min(1).optional().describe("candidate bones; default: the slot's bone + its parent + its children"),
+    radius: z3.number().positive().optional().describe("falloff scale in world px, default 1; larger spreads influence across more bones, smaller binds tighter to the nearest one; no cutoff"),
+    maxInfluences: z3.number().int().min(1).default(2).describe("bones per vertex")
   },
   async ({ path, id, bones, radius, maxInfluences }) => mutateWith(path, (d, say) => {
     const att = meshOf(d, id);
@@ -4860,12 +5964,12 @@ tool(
   "Replace a mesh's geometry arrays (only the given ones): `uvs` (2 per vertex, 0..1 in the asset image), `triangles` (3 indices each), `hull` (leading vertices that form the outline), and its rest shape as either `vertices` (2 per vertex, slot-bone local) or `weights` (skinned) \u2014 giving one drops the other. Deform `vertices` keys whose length no longer fits are dropped. For tracing a mesh from the image use rig_mesh_from_image.",
   {
     path: Path,
-    id: z2.string().describe("mesh attachment id"),
-    vertices: z2.array(z2.number()).optional(),
+    id: z3.string().describe("mesh attachment id"),
+    vertices: z3.array(z3.number()).optional(),
     weights: WeightsIn.optional(),
-    uvs: z2.array(z2.number()).optional(),
-    triangles: z2.array(z2.number().int().nonnegative()).optional(),
-    hull: z2.number().int().nonnegative().optional()
+    uvs: z3.array(z3.number()).optional(),
+    triangles: z3.array(z3.number().int().nonnegative()).optional(),
+    hull: z3.number().int().nonnegative().optional()
   },
   async ({ path, id, ...patch }) => mutateWith(path, (d, say) => {
     const { doc, dropped } = setMesh(d, meshOf(d, id).id, patch);
@@ -4876,7 +5980,7 @@ tool(
 tool(
   "rig_set_weights",
   "Replace a mesh's skinning by hand: one influence list per vertex (uv order), each {bone, x, y, w} holding the vertex in that bone's local space; a list's weights should sum to 1. Drops the mesh's unweighted `vertices` and any deform `vertices` keys whose length no longer fits. rig_auto_weights computes these from bone distance.",
-  { path: Path, id: z2.string().describe("mesh attachment id"), weights: WeightsIn },
+  { path: Path, id: z3.string().describe("mesh attachment id"), weights: WeightsIn },
   async ({ path, id, weights }) => mutateWith(path, (d, say) => {
     const { doc, dropped } = setWeights(d, meshOf(d, id).id, weights);
     if (dropped.length) say(`dropped deform tracks: ${dropped.join(", ")}`);
@@ -4886,19 +5990,19 @@ tool(
 tool(
   "rig_remove_attachment",
   "Remove an attachment; slots showing it become hidden, keys naming it become null.",
-  { path: Path, id: z2.string() },
+  { path: Path, id: z3.string() },
   async ({ path, id }) => mutate(path, (d) => removeAttachment(d, id))
 );
 tool(
   "rig_remove_slot",
   "Remove a slot and its tracks.",
-  { path: Path, id: z2.string() },
+  { path: Path, id: z3.string() },
   async ({ path, id }) => mutate(path, (d) => removeSlot(d, id), true)
 );
 tool(
   "rig_set_draw_order",
   "Setup draw order in one call: `order` lists EVERY slot back-to-front (the same order a drawOrder key uses); each slot gets z = its index. For an animated reorder key the drawOrder track with rig_set_keys instead.",
-  { path: Path, order: z2.array(z2.string()).min(1) },
+  { path: Path, order: z3.array(z3.string()).min(1) },
   async ({ path, order }) => mutate(path, (d) => setDrawOrder(d, order))
 );
 function namesId(v, id) {
@@ -4910,7 +6014,7 @@ function namesId(v, id) {
 tool(
   "rig_rename",
   "Rename a bone, slot, attachment, asset or constraint and rewrite EVERY reference to it (parents, slot bones, chains and targets, mesh/path influences, slot attachments, key values, drawOrder keys, tracks). Roles stay. Templates in presets.json are a separate file and are not rewritten \u2014 re-save them if they name the old id. An animation's own preset.params (rig_apply_preset) is left alone too \u2014 the reply names any that still refer to the old id, since a blind substitution across differently-shaped params would be unsafe.",
-  { path: Path, kind: z2.enum(["bone", "slot", "attachment", "asset", "constraint"]), id: z2.string(), to: z2.string() },
+  { path: Path, kind: z3.enum(["bone", "slot", "attachment", "asset", "constraint"]), id: z3.string(), to: z3.string() },
   async ({ path, kind, id, to }) => mutateWith(path, async (d, say) => {
     if (await exists2(libraryFor(path))) say(`note: ${libraryFor(path)} is not rewritten \u2014 templates that name "${id}" by id still do`);
     const next = rename2(d, kind, id, to);
@@ -4920,25 +6024,27 @@ tool(
     return next;
   }, true)
 );
-var ConstraintBones = z2.array(z2.string()).min(1).optional().describe("bones the constraint drives (replaces the whole list); required when it is created");
-var ConstraintOrder = z2.number().int().optional().describe("solver order, lowest first (default 0); equal orders keep document order");
-var PathMixes = { mixRotate: z2.number().optional(), mixX: z2.number().optional(), mixY: z2.number().optional() };
-var Mixes = { ...PathMixes, mixScaleX: z2.number().optional(), mixScaleY: z2.number().optional(), mixShearY: z2.number().optional() };
+var ConstraintBones = z3.array(z3.string()).min(1).optional().describe("bones the constraint drives (replaces the whole list); required when it is created");
+var ConstraintOrder = z3.number().int().optional().describe("solver order, lowest first (default 0); equal orders keep document order");
+var PathMixes = { mixRotate: z3.number().optional(), mixX: z3.number().optional(), mixY: z3.number().optional() };
+var Mixes = { ...PathMixes, mixScaleX: z3.number().optional(), mixScaleY: z3.number().optional(), mixShearY: z3.number().optional() };
 var CONSTRAINT_DOC = "Constraints are solved after the bone tree, in `order`, and OVERWRITE the bones they drive: keying such a bone directly does nothing visible \u2014 key the target bone (or this constraint's mix, an ordinary number track) instead. Ids are shared by the three kinds and a constraint's kind is fixed once created; rig_remove_constraint drops it together with its tracks.";
 tool(
   "rig_set_ik",
-  "Create or patch an IK constraint: bend a chain of 1-2 bones so its tip reaches a TARGET BONE \u2014 move the target, the limb follows. `bones` is the chain parent\u2192child (1 or 2 bones; the format has no longer chains), `target` is a BONE, normally a marker parented to the root so the limb reaches a place in the world. `bendPositive` picks which way a two-bone chain buckles (knee forward or backward), `softness` eases the last px before full extension, `compress`/`stretch` let the chain shorten/lengthen to reach, `mix` 0..1 fades the whole constraint. Fields are merged, so {id, mix} patches only the mix. To rig a limb from scratch call rig_add_ik_chain instead: it creates the target bone at the current tip and derives `bendPositive` from the pose. " + CONSTRAINT_DOC,
+  "Create or patch an IK constraint: bend a chain of bones so its tip reaches a TARGET BONE \u2014 move the target, the limb follows. `bones` is the chain parent\u2192child (1\u20132 bones: analytic solve; 3+: iterative CCD), `target` is a BONE, normally a marker parented to the root so the limb reaches a place in the world. `bendPositive` picks which way a two-bone chain buckles (knee forward or backward), `softness` eases the last px before full extension, `compress`/`stretch` let the chain shorten/lengthen to reach, `mix` 0..1 fades the whole constraint. Fields are merged, so {id, mix} patches only the mix. To rig a limb from scratch call rig_add_ik_chain instead: it creates the target bone at the current tip and derives `bendPositive` from the pose. " + CONSTRAINT_DOC,
   {
     path: Path,
-    id: z2.string(),
+    id: z3.string(),
     bones: ConstraintBones,
-    target: z2.string().optional().describe("BONE the chain reaches for"),
-    mix: z2.number().optional(),
-    softness: z2.number().optional(),
-    bendPositive: z2.boolean().optional(),
-    compress: z2.boolean().optional(),
-    stretch: z2.boolean().optional(),
-    uniform: z2.boolean().optional(),
+    target: z3.string().optional().describe("BONE the chain reaches for"),
+    mix: z3.number().optional(),
+    softness: z3.number().optional(),
+    bendPositive: z3.boolean().optional(),
+    iterations: z3.number().int().min(1).max(1e3).optional(),
+    tolerance: z3.number().positive().optional(),
+    compress: z3.boolean().optional(),
+    stretch: z3.boolean().optional(),
+    uniform: z3.boolean().optional(),
     order: ConstraintOrder
   },
   async ({ path, id, ...patch }) => mutate(path, (d) => setConstraint(d, "ik", id, patch))
@@ -4948,17 +6054,17 @@ tool(
   "Create or patch a transform constraint: copy a TARGET BONE's transform onto the driven bones, channel by channel (mixRotate/mixX/mixY/mixScaleX/mixScaleY/mixShearY, 0..1, each keyable), with constant offsets (rotation/x/y/scaleX/scaleY/shearY) added on top. `local` copies in the bones' local space instead of world; `relative` ADDS the target's transform to the bone's own instead of replacing it. Use it to make parts follow one control: a cape following the torso, a mirrored limb, a bone that inherits half the rotation. Fields are merged; `bones` and `target` (a BONE) are required when it is created. " + CONSTRAINT_DOC,
   {
     path: Path,
-    id: z2.string(),
+    id: z3.string(),
     bones: ConstraintBones,
-    target: z2.string().optional().describe("BONE whose transform is copied"),
-    local: z2.boolean().optional(),
-    relative: z2.boolean().optional(),
-    rotation: z2.number().optional(),
-    x: z2.number().optional(),
-    y: z2.number().optional(),
-    scaleX: z2.number().optional(),
-    scaleY: z2.number().optional(),
-    shearY: z2.number().optional(),
+    target: z3.string().optional().describe("BONE whose transform is copied"),
+    local: z3.boolean().optional(),
+    relative: z3.boolean().optional(),
+    rotation: z3.number().optional(),
+    x: z3.number().optional(),
+    y: z3.number().optional(),
+    scaleX: z3.number().optional(),
+    scaleY: z3.number().optional(),
+    shearY: z3.number().optional(),
     ...Mixes,
     order: ConstraintOrder
   },
@@ -4969,15 +6075,15 @@ tool(
   "Create or patch a path constraint: place and orient bones along the curve of a path attachment (a tail following a spline, a chain crawling along a road). `target` is a SLOT whose visible attachment is a path \u2014 build the curve with rig_set_path_attachment, then show it with rig_set_slot {attachment}. positionMode fixed|percent (position in px along the curve, or 0..1 of its length), spacingMode length|fixed|percent|proportional (how the bones are spread along it), rotateMode tangent|chain|chainScale. `position` and `spacing` slide the bones along the curve and are the usual things to key. Fields are merged; `bones` and `target` are required when it is created. " + CONSTRAINT_DOC,
   {
     path: Path,
-    id: z2.string(),
+    id: z3.string(),
     bones: ConstraintBones,
-    target: z2.string().optional().describe("SLOT showing a path attachment"),
-    positionMode: z2.enum(["fixed", "percent"]).optional(),
-    spacingMode: z2.enum(["length", "fixed", "percent", "proportional"]).optional(),
-    rotateMode: z2.enum(["tangent", "chain", "chainScale"]).optional(),
-    rotation: z2.number().optional(),
-    position: z2.number().optional(),
-    spacing: z2.number().optional(),
+    target: z3.string().optional().describe("SLOT showing a path attachment"),
+    positionMode: z3.enum(["fixed", "percent"]).optional(),
+    spacingMode: z3.enum(["length", "fixed", "percent", "proportional"]).optional(),
+    rotateMode: z3.enum(["tangent", "chain", "chainScale"]).optional(),
+    rotation: z3.number().optional(),
+    position: z3.number().optional(),
+    spacing: z3.number().optional(),
     ...PathMixes,
     order: ConstraintOrder
   },
@@ -4986,7 +6092,7 @@ tool(
 tool(
   "rig_remove_constraint",
   "Remove a constraint of any kind (ik / transform / path) by id, together with its animation tracks; the bones it drove fall back to their keyed or rest transforms.",
-  { path: Path, id: z2.string() },
+  { path: Path, id: z3.string() },
   async ({ path, id }) => mutate(path, (d) => removeConstraint(d, id))
 );
 tool(
@@ -4994,13 +6100,14 @@ tool(
   "Rig a limb in ONE call \u2014 the easy path to IK. Give the chain's LAST bone (shin, forearm): the chain is [parent, bone] when that parent has exactly this one child, otherwise just the bone. The tool creates a target bone (role ik_target) at the chain's current tip AS A CHILD OF THE ROOT BONE \u2014 never inside the chain, where the IK would drag its own target \u2014 and an IK constraint `<bone>_ik` whose `bendPositive` is derived from the CURRENT pose, so adding it does not move the rig. It is solved last (highest order). When the two-bone chain would reach up to the root itself, it falls back to the single bone (which just aims at the target) and says so. Afterwards pose the limb by moving or keying the TARGET bone (or fade the constraint with its mix), not the chain's rotations.",
   {
     path: Path,
-    bone: z2.string().describe("the chain's tip bone, e.g. shin or forearm; it needs a parent"),
-    target: z2.string().optional().describe("id for the new target bone; default <bone>_ik"),
-    mix: z2.number().default(1),
-    softness: z2.number().default(0)
+    bone: z3.string().describe("the chain's tip bone, e.g. shin or forearm; it needs a parent"),
+    bones: z3.array(z3.string()).min(1).optional().describe("explicit parent-to-tip chain for long IK"),
+    target: z3.string().optional().describe("id for the new target bone; default <bone>_ik"),
+    mix: z3.number().default(1),
+    softness: z3.number().default(0)
   },
-  async ({ path, bone, target, mix, softness }) => mutateWith(path, (d, say) => {
-    const r = addIkChain(d, bone, { target, mix, softness });
+  async ({ path, bone, target, mix, softness, bones }) => mutateWith(path, (d, say) => {
+    const r = addIkChain(d, bone, { target, mix, softness, bones });
     say(`ik "${bone}_ik": chain ${r.chain.join(",")}${r.note ? ` (${r.note})` : ""} \u2192 new target bone "${r.target}" (bend ${r.bendPositive ? "+" : "-"}); move or key "${r.target}" to pose the limb`);
     return r.doc;
   }, true)
@@ -5010,12 +6117,12 @@ tool(
   "Create or replace a PATH attachment. Two forms, exactly one per call (both need at least 2 anchors, 3 when closed): `points` \u2014 anchors in DOCUMENT coordinates \u2014 rebuilds the curve with fresh Catmull-Rom tangents, so it DESTROYS a skinned path's weights and any authored tangents; the form for drawing a path from scratch. `vertices` / `weights` \u2014 raw control points [cPrev, p, cNext] per anchor, in the slot bone's space (or skinned: `weights` gives one influence list per control point, {bone,x,y,w} like rig_set_weights) \u2014 the ONLY form that preserves weights and authored tangents; use it to edit an existing path, and rig_path_anchor to add or remove an anchor without a full replace. Show it with rig_set_slot {id: <slot>, attachment: <id>}, then drive bones along it with rig_set_path. `closed` keeps its current value when omitted on an existing path (false on creation). Deform `vertices` keys whose length no longer fits the new geometry are dropped \u2014 and a `points` rebuild that happens to keep the same count keeps them too, now deforming a DIFFERENT curve, which is the other reason to edit through the raw form. `lengths` are always re-measured, so an imported path's stored values move by up to ~0.5 % even when the shape is byte-identical; that is nothing to act on, because every path here has `constantSpeed: true` (all of ross's do, and no tool can turn it off) and the runtime then measures the posed curve itself and never reads them.",
   {
     path: Path,
-    id: z2.string().describe("path attachment id"),
-    slot: z2.string(),
-    points: z2.array(z2.tuple([z2.number(), z2.number()])).min(2).optional().describe("[[x, y], \u2026] anchors in document space"),
-    vertices: z2.array(z2.number()).optional(),
+    id: z3.string().describe("path attachment id"),
+    slot: z3.string(),
+    points: z3.array(z3.tuple([z3.number(), z3.number()])).min(2).optional().describe("[[x, y], \u2026] anchors in document space"),
+    vertices: z3.array(z3.number()).optional(),
     weights: WeightsIn.optional(),
-    closed: z2.boolean().optional()
+    closed: z3.boolean().optional()
   },
   async ({ path, id, slot, points, vertices, weights, closed }) => mutateWith(path, (d, say) => {
     const { doc: next, dropped } = setPathAttachment(d, id, slot, { points, vertices, weights, closed });
@@ -5030,10 +6137,10 @@ tool(
   "Insert or remove one anchor of a path attachment. `insert` splits the curve AFTER anchor `index` at `t` (strictly between 0 and 1, default 0.5) using de Casteljau, so the curve keeps its exact shape in EVERY pose, not just at rest, and a weighted path keeps its skinning (each new control point is the c*w-weighted blend of the split segment's influences, which is an identity in the bone matrices). It also keeps the attachment's DEFORM tracks: the same coefficients blend the four source control points' offsets, so the ANIMATED curve is unchanged too \u2014 an insert loses nothing. `remove` drops the anchor's three control points, which does change the shape, and with it any deform key whose length no longer fits (reported in the reply).",
   {
     path: Path,
-    id: z2.string().describe("path attachment id"),
-    op: z2.enum(["insert", "remove"]),
-    index: z2.number().int().nonnegative().describe("anchor index, 0-based (anchors are the vertices at 1, 4, 7, \u2026)"),
-    t: z2.number().gt(0).lt(1).optional().describe("insert only: where in the segment, strictly between 0 and 1 (an endpoint is the anchor that is already there), default 0.5")
+    id: z3.string().describe("path attachment id"),
+    op: z3.enum(["insert", "remove"]),
+    index: z3.number().int().nonnegative().describe("anchor index, 0-based (anchors are the vertices at 1, 4, 7, \u2026)"),
+    t: z3.number().gt(0).lt(1).optional().describe("insert only: where in the segment, strictly between 0 and 1 (an endpoint is the anchor that is already there), default 0.5")
   },
   async ({ path, id, op, index, t }) => mutateWith(path, (d, say) => {
     const { doc, dropped } = pathAnchorOp(d, id, op, index, t);
@@ -5047,9 +6154,9 @@ tool(
   "Generate an animation from a parametric preset (replaces the animation with the same id). Built-in presets bind to bones by `role`; template presets (rig_save_as_preset) come from the library and match bones by role, then id. Re-tune by re-applying with different params.\nCharacter: idle_breathing (bulges the torso image, neck/waist pinned), weight_shift (feet stay planted), win_bounce, anticipation_shake, blink, mouth_talk. Symbol: symbol_idle, symbol_win, dim (state pose, use as base).\n" + presetHelp,
   {
     path: Path,
-    preset: z2.string().describe("built-in name or a template name from the library"),
-    params: z2.record(z2.unknown()).default({}).describe("partial override of defaults"),
-    id: z2.string().optional().describe("animation id for templates (default: template name)"),
+    preset: z3.string().describe("built-in name or a template name from the library"),
+    params: z3.record(z3.unknown()).default({}).describe("partial override of defaults"),
+    id: z3.string().optional().describe("animation id for templates (default: template name)"),
     library: Library
   },
   async ({ path, preset, params, id, library }) => mutate(path, async (d) => {
@@ -5062,7 +6169,7 @@ tool(
 tool(
   "rig_save_as_preset",
   'Turn a finished animation into a reusable template: tracks stored relative to rest and keyed by bone role, params amplitude (all relative values), speed (time) and optional named groups of source tracks (`{"turn": ["bone.root.rotation"]}`) that become their own multipliers. Apply on any rig with rig_apply_preset.',
-  { path: Path, animation: z2.string(), name: z2.string().describe("snake_case template name"), groups: z2.record(z2.array(z2.string())).optional(), library: Library },
+  { path: Path, animation: z3.string(), name: z3.string().describe("snake_case template name"), groups: z3.record(z3.array(z3.string())).optional(), library: Library },
   async ({ path, animation, name, groups, library }) => {
     try {
       const tpl = extractTemplate(await load(path), animation, name, groups);
@@ -5094,7 +6201,7 @@ ${tpls.length ? tpls.map(describeTemplate).join("\n") : "  none"}`);
 tool(
   "rig_get_preset",
   "One preset as JSON: {builtin: true, name, defaults} for a built-in, or the library template (tracks, params). For editors that preview parameter changes locally.",
-  { path: Path, preset: z2.string(), library: Library },
+  { path: Path, preset: z3.string(), library: Library },
   async ({ path, preset, library }) => {
     try {
       if (preset in presets) {
@@ -5112,9 +6219,9 @@ tool(
 tool(
   "rig_set_keys",
   "Set the keys of ONE track (creates the animation if missing; manual keys drop the animation's preset link). Replaces all keys unless merge=true, which replaces only keys at the given times and keeps the rest. duration/loop are optional and persist once set. " + KEY_DOC,
-  { path: Path, animation: z2.string(), ...TrackRef, keys: z2.array(KeyIn), merge: z2.boolean().default(false), duration: z2.number().optional(), loop: z2.boolean().optional() },
-  async ({ path, animation, target, id, prop, keys, merge, duration, loop }) => mutate(path, (d) => {
-    let n = setKeys(d, animation, { target, id, prop }, keys.map(roundKey), duration, { merge });
+  { path: Path, animation: z3.string(), ...TrackRef, keys: z3.array(KeyIn), merge: z3.boolean().default(false), duration: z3.number().optional(), loop: z3.boolean().optional() },
+  async ({ path, animation, target, id, prop, interpolation, keys, merge, duration, loop }) => mutate(path, (d) => {
+    let n = setKeys(d, animation, { target, id, prop, interpolation }, keys.map(roundKey), duration, { merge });
     if (loop !== void 0) n = { ...n, animations: n.animations.map((a) => a.id === animation ? { ...a, loop } : a) };
     return n;
   })
@@ -5122,10 +6229,10 @@ tool(
 tool(
   "rig_set_tracks",
   "Set several tracks of one animation in a single call (same semantics as rig_set_keys for each). " + KEY_DOC,
-  { path: Path, animation: z2.string(), tracks: z2.array(z2.object({ ...TrackRef, keys: z2.array(KeyIn) })).min(1), merge: z2.boolean().default(false), duration: z2.number().optional(), loop: z2.boolean().optional() },
+  { path: Path, animation: z3.string(), tracks: z3.array(z3.object({ ...TrackRef, keys: z3.array(KeyIn) })).min(1), merge: z3.boolean().default(false), duration: z3.number().optional(), loop: z3.boolean().optional() },
   async ({ path, animation, tracks, merge, duration, loop }) => mutate(path, (d) => {
     let n = d;
-    for (const t of tracks) n = setKeys(n, animation, { target: t.target, id: t.id, prop: t.prop }, t.keys.map(roundKey), duration, { merge });
+    for (const t of tracks) n = setKeys(n, animation, { target: t.target, id: t.id, prop: t.prop, interpolation: t.interpolation }, t.keys.map(roundKey), duration, { merge });
     if (loop !== void 0) n = { ...n, animations: n.animations.map((a) => a.id === animation ? { ...a, loop } : a) };
     return n;
   })
@@ -5135,11 +6242,11 @@ tool(
   "Put a bone at a point in DOCUMENT coordinates \u2014 the same coordinates rig_get_pose reports and rig_render_preview draws. Without `animation` it moves the setup pose; with one it keys x and y at `t`, creating the animation if it does not exist yet (`t` and `ease` without an `animation` are an error, not a no-op). If the bone is driven by a LIVE ik constraint the edit is redirected to that constraint's TARGET BONE, whose origin is then what lands on the point (the answer says so), because writing the bone itself would be overwritten by the solver. For a rig_add_ik_chain limb that target sits at the chain's tip, so AT FULL MIX the tip reaches the point while the named bone only turns \u2014 a goal on the chain's FIRST bone does not move that bone's origin at all, and a partly mixed chain lands the target but leaves the tip short. A live transform or path constraint refuses instead: nothing can be written there, so key its mix to 0 at that time or edit the constraint. The point is converted using the pose AT THAT TIME, so a turned parent is accounted for. The result is re-evaluated before it is saved: if what was written does not actually land on the point (a target a second solver owns, or one parented inside the chain that aims it) the call fails and writes nothing. On success the answer gives the NAMED bone's world origin and tip after the edit.",
   {
     path: Path,
-    bone: z2.string(),
-    x: z2.number(),
-    y: z2.number(),
-    animation: z2.string().optional(),
-    t: z2.number().min(0).optional(),
+    bone: z3.string(),
+    x: z3.number(),
+    y: z3.number(),
+    animation: z3.string().optional(),
+    t: z3.number().min(0).optional(),
     ease: Ease.optional()
   },
   async ({ path, bone, x, y, ...opts }) => mutateWith(path, (d, say) => {
@@ -5154,11 +6261,11 @@ tool(
   "Copy the bone tracks of one set of bones onto another, pair by pair, optionally shifted in time and mirrored. `phase` is a fraction of the animation's duration (0.5 = half a cycle later, 1 wraps back to 0). `mirrorX` negates x, rotation, shearX and shearY, which mirrors the motion across the PARENT's y axis \u2014 that is a left/right mirror only when the destination's parent frame is itself the mirror image of the source's, which is not automatic: on a rig whose shoulders are not conjugate frames a mirrored arm copy points the SAME way in the document. Destination tracks are replaced per prop, not merged. Data can be lost: a track keyed at both 0 and `duration` with DIFFERENT values loses the segment into that last key when `phase` shifts it, and a non-looping animation has the segment between its last and first key split \u2014 both are reported in the answer. This is how the second leg of a cycle is made from the first \u2014 it is an operation, not a preset: nothing is stored or reused.",
   {
     path: Path,
-    animation: z2.string(),
-    from: z2.array(z2.string()).min(1),
-    to: z2.array(z2.string()).min(1),
-    phase: z2.number().min(0).max(1).default(0),
-    mirrorX: z2.boolean().default(false)
+    animation: z3.string(),
+    from: z3.array(z3.string()).min(1),
+    to: z3.array(z3.string()).min(1),
+    phase: z3.number().min(0).max(1).default(0),
+    mirrorX: z3.boolean().default(false)
   },
   async ({ path, animation, from, to, phase, mirrorX }) => mutateWith(path, (d, say) => {
     const { doc, copied, empty, lossy } = copyTracks(d, animation, from, to, { phase, mirrorX });
@@ -5172,7 +6279,7 @@ tool(
 tool(
   "rig_adjust_track",
   "Re-tune an existing track without retyping keys: amplitude scales its deviation from the rest value (0.5 = half as strong, 2 = twice; scale props as ratios), offset adds a constant, timeScale stretches its key times (duration grows to fit). Drops the preset link.",
-  { path: Path, animation: z2.string(), ...TrackRef, amplitude: z2.number().optional(), offset: z2.number().optional(), timeScale: z2.number().positive().optional() },
+  { path: Path, animation: z3.string(), ...TrackRef, amplitude: z3.number().optional(), offset: z3.number().optional(), timeScale: z3.number().positive().optional() },
   async ({ path, animation, target, id, prop, ...adj }) => mutate(path, (d) => adjustTrack(d, animation, { target, id, prop }, adj))
 );
 tool(
@@ -5180,47 +6287,108 @@ tool(
   "Animation properties without touching keys: duration (must cover the last key/event), loop, events (full list), rename. Creates the animation if missing.",
   {
     path: Path,
-    id: z2.string(),
-    duration: z2.number().positive().optional(),
-    loop: z2.boolean().optional(),
-    events: z2.array(z2.object({ t: z2.number().nonnegative(), name: z2.string(), payload: z2.record(z2.unknown()).optional() })).optional(),
-    rename: z2.string().optional()
+    id: z3.string(),
+    duration: z3.number().positive().optional(),
+    loop: z3.boolean().optional(),
+    events: z3.array(z3.object({ t: z3.number().nonnegative(), name: z3.string(), payload: z3.record(z3.unknown()).optional() })).optional(),
+    rename: z3.string().optional()
   },
   async ({ path, id, ...patch }) => mutate(path, (d) => setAnimation(d, id, patch))
 );
 tool(
   "rig_remove_keys",
   "Remove the keys of one track at the given times; an emptied track is dropped. Drops the preset link.",
-  { path: Path, animation: z2.string(), ...TrackRef, times: z2.array(z2.number()).min(1) },
+  { path: Path, animation: z3.string(), ...TrackRef, times: z3.array(z3.number()).min(1) },
   async ({ path, animation, target, id, prop, times: times2 }) => mutate(path, (d) => removeKeys(d, animation, { target, id, prop }, times2))
 );
 tool(
   "rig_remove_animation",
   "Delete an animation.",
-  { path: Path, id: z2.string() },
+  { path: Path, id: z3.string() },
   async ({ path, id }) => mutate(path, (d) => removeAnimation(d, id), true)
 );
+tool(
+  "rig_order_constraints",
+  "Sort constraints by what they read and write, including target ancestors and skinned paths. Cycles are refused.",
+  { path: Path },
+  async ({ path }) => mutate(path, orderConstraints)
+);
+tool(
+  "rig_gradient_weights",
+  "Skin a mesh with a gradient along ordered chain joints, preserving its setup geometry.",
+  { path: Path, id: z3.string(), bones: z3.array(z3.string()).min(2) },
+  async ({ path, id, bones }) => mutate(path, (d) => gradientWeights(d, id, bones))
+);
+tool(
+  "rig_smooth_weights",
+  "Smooth weights over triangle neighbours. Locked vertex indices keep their weights. Deform tracks are dropped if the influence layout changes.",
+  { path: Path, id: z3.string(), iterations: z3.number().int().min(1).max(100).default(3), strength: z3.number().min(0).max(1).default(0.5), locked: z3.array(z3.number().int().nonnegative()).default([]) },
+  async ({ path, id, iterations, strength, locked }) => mutate(path, (d) => smoothWeights(d, id, iterations, strength, locked))
+);
+tool(
+  "rig_pin_weights",
+  "Bind selected mesh vertices rigidly to one bone. Select by indices or document-space rectangle, e.g. the solid body of a prop while leaving its strap flexible.",
+  { path: Path, id: z3.string(), bone: z3.string(), vertices: z3.array(z3.number().int().nonnegative()).optional(), region: z3.tuple([z3.number(), z3.number(), z3.number().positive(), z3.number().positive()]).optional() },
+  async ({ path, id, bone, vertices, region }) => mutate(path, (d) => pinWeights(d, id, bone, vertices, region))
+);
+tool(
+  "rig_attach_to_bone",
+  "At an animation time, switch a prop bone to follow a target bone without changing its evaluated world pose. Creates keyed transform constraints and computes offsets after IK. Author successive contacts in time order; key hand attachment swaps at the same time.",
+  { path: Path, animation: z3.string(), bone: z3.string(), target: z3.string(), t: z3.number().nonnegative() },
+  async ({ path, animation, bone, target, t }) => mutate(path, (d) => attachToBone(d, animation, bone, target, t))
+);
+tool(
+  "rig_bake_secondary",
+  "Bake velocity-driven damped spring rotations into editable PCHIP tracks. Uses evaluated world rotation or x/y motion (including IK). A looping driver must close; loop state is settled before baking and starts at setup within maxAngle. No runtime physics is required.",
+  { path: Path, animation: z3.string(), driver: z3.string(), driverProp: z3.enum(["rotation", "x", "y"]).default("rotation"), bones: z3.array(z3.string()).min(1), frequency: z3.number().positive().default(2.5), damping: z3.number().positive().default(0.65), gain: z3.number().default(0.2), fps: z3.number().int().min(1).max(240).default(60), maxAngle: z3.number().positive().default(30) },
+  async ({ path, animation, ...opts }) => mutate(path, (d) => bakeSecondary(d, animation, opts))
+);
 tool(
   "rig_render_preview",
   "Render frames of an animation (or the rest pose) as a contact-sheet PNG, plus the rig_check findings for that animation (or a positive one-liner). Use it after every change to SEE the result. overlayBones=true draws the skeleton with ids; onionSkin=true ghosts the previous frame of the sheet under each frame (the first frame has no ghost); region=[x,y,w,h] in document px crops to a detail (a face) so small motion is legible at low token cost.",
   {
     path: Path,
-    animation: z2.string().optional(),
-    fps: z2.number().default(8),
-    count: z2.number().int().optional(),
-    times: z2.array(z2.number()).optional(),
-    overlayBones: z2.boolean().default(false),
-    onionSkin: z2.boolean().default(false),
-    region: z2.tuple([z2.number(), z2.number(), z2.number(), z2.number()]).optional(),
-    scale: z2.number().default(0.5).describe("downscale to save tokens"),
-    sheetColumns: z2.number().int().default(4),
-    saveTo: z2.string().optional().describe("also write sheet PNG here")
+    animation: z3.string().optional(),
+    fps: z3.number().default(8),
+    count: z3.number().int().optional(),
+    times: z3.array(z3.number()).optional(),
+    transparent: z3.boolean().default(false),
+    background: z3.string().optional(),
+    weightBone: z3.string().optional(),
+    debugFillMasks: z3.record(z3.string()).optional(),
+    framesDir: z3.string().optional(),
+    overlayBones: z3.boolean().default(false),
+    onionSkin: z3.boolean().default(false),
+    region: z3.tuple([z3.number(), z3.number(), z3.number(), z3.number()]).optional(),
+    scale: z3.number().default(0.5).describe("downscale to save tokens"),
+    sheetColumns: z3.number().int().default(4),
+    saveTo: z3.string().optional().describe("also write sheet PNG here")
   },
-  async ({ path, saveTo, ...opts }) => {
+  async ({ path, saveTo, framesDir, ...opts }) => {
     try {
-      const doc = await load(path);
-      const r = await renderPreview(doc, { assetsDir: dirname6(path), ...opts });
-      if (saveTo) await writeFile6(saveTo, r.sheet);
+      const raw = await readFile9(path, "utf8");
+      const doc = parse(JSON.parse(raw));
+      const r = await renderPreview(doc, { assetsDir: dirname8(path), ...opts });
+      if (saveTo) await writeFile7(saveTo, r.sheet);
+      if (framesDir) {
+        const { mkdir: mkdir8 } = await import("node:fs/promises");
+        await mkdir8(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 = {
+          version: 1,
+          rigFile: sha256(raw),
+          capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          identity: r.identity,
+          animation: opts.animation ?? null,
+          transparent: opts.transparent,
+          scale: opts.scale,
+          times: r.times,
+          frames,
+          render: { background: opts.background, overlayBones: opts.overlayBones, onionSkin: opts.onionSkin, weightBone: opts.weightBone, debugFillMasks: opts.debugFillMasks ?? {}, region: opts.region }
+        };
+        await writeFile7(join9(framesDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+      }
       return { text: `${r.times.length} frames @ ${r.width}x${r.height}, t=[${r.times.join(", ")}]
 ${previewCheck(doc, opts.animation)}`, image: r.sheet };
     } catch (e) {
@@ -5231,14 +6399,55 @@ ${previewCheck(doc, opts.animation)}`, image: r.sheet };
 tool(
   "rig_export",
   "Export for a game: pack all PNG layers into <outDir>/atlas.png and write <outDir>/rig.json whose assets point into it (asset.frame). One texture per rig instead of one per layer.",
-  { path: Path, outDir: z2.string().describe("absolute, or relative to rig.json dir"), padding: z2.number().int().default(2), maxSize: z2.number().int().default(4096) },
+  { path: Path, outDir: z3.string().describe("absolute, or relative to rig.json dir"), padding: z3.number().int().default(2), maxSize: z3.number().int().default(4096) },
   async ({ path, outDir, padding, maxSize }) => {
     try {
       const out = resolveFrom(path, outDir);
-      const doc = await buildAtlas(await load(path), dirname6(path), out, { padding, maxSize });
-      const [w, h] = pngSize(await readFile8(join7(out, "atlas.png")));
-      return text(`\u2192 ${join7(out, "rig.json")}
-\u2192 ${join7(out, "atlas.png")} (${w}x${h}, ${doc.assets.length} frames)`);
+      const doc = await buildAtlas(await load(path), dirname8(path), out, { padding, maxSize });
+      const [w, h] = pngSize(await readFile9(join9(out, "atlas.png")));
+      return text(`\u2192 ${join9(out, "rig.json")}
+\u2192 ${join9(out, "atlas.png")} (${w}x${h}, ${doc.assets.length} frames)`);
+    } catch (e) {
+      return fail(e);
+    }
+  }
+);
+tool(
+  "rig_export_video",
+  "Export runtime playback to MP4 (60 fps by default). Requires ffmpeg. Duration is rounded to a whole frame and reported. Output has an opaque presentation background; use transparent preview frames for alpha QA.",
+  { path: Path, animation: z3.string(), outFile: z3.string(), fps: z3.number().int().min(1).max(240).default(60), scale: z3.number().positive().default(1), background: z3.string().optional(), weightBone: z3.string().optional(), debugFillMasks: z3.record(z3.string()).optional() },
+  async ({ path, outFile, ...opts }) => {
+    try {
+      const result = await exportVideo(await load(path), { assetsDir: dirname8(path), outFile: resolveFrom(path, outFile), ...opts });
+      return text(`${resolveFrom(path, outFile)}: ${result.frames} frames, ${result.fps} fps, ${result.duration}s`);
+    } catch (e) {
+      return fail(e);
+    }
+  }
+);
+tool(
+  "rig_verify_render",
+  "Fail if render inputs or outputs changed, frames are absent/extra, or the capture does not cover the explicit expected times. Run before image gates; a manifest alone is not an art-quality pass.",
+  { path: Path, framesDir: z3.string(), animation: z3.string().optional(), times: z3.array(z3.number().nonnegative()).min(1), transparent: z3.boolean().optional() },
+  async ({ path, framesDir, ...expected }) => {
+    try {
+      const here = dirname8(fileURLToPath2(import.meta.url));
+      const source = join9(here, "preview/harness.js"), bundled = join9(here, "harness.js");
+      const manifest = await verifyRenderManifest(path, framesDir, { ...expected, renderer: await exists2(source) ? source : bundled });
+      return text(`verified ${manifest.frames.length}/${expected.times.length} frames; inputs, renderer and frame hashes match`);
+    } catch (e) {
+      return fail(e);
+    }
+  }
+);
+tool(
+  "rig_run_gates",
+  "Run explicit motion, proportion/contact, flash/pose, animation-ID and real AnimationState transition gates. Report sampling, amplitudes, speed/acceleration/jerk and failures; thresholds are supplied by the brief.",
+  { path: Path, config: GateConfig },
+  async ({ path, config }) => {
+    try {
+      const report = runGates(await load(path), config);
+      return { text: JSON.stringify(report, null, 2), isError: !report.pass };
     } catch (e) {
       return fail(e);
     }
@@ -5249,7 +6458,7 @@ tool(
 var TYPES = { ".html": "text/html; charset=utf-8", ".js": "text/javascript", ".css": "text/css", ".map": "application/json", ".json": "application/json", ".png": "image/png", ".jpg": "image/jpeg", ".webp": "image/webp" };
 async function startEditorServer(opts) {
   const root3 = resolve2(opts.root);
-  const assets = resolve2(opts.assets ?? fileURLToPath2(new URL("../..", import.meta.url)));
+  const assets = resolve2(opts.assets ?? fileURLToPath3(new URL("../..", import.meta.url)));
   const inside = (rel) => {
     const abs = resolve2(root3, rel);
     return abs === root3 || abs.startsWith(root3 + sep) ? abs : void 0;
@@ -5262,7 +6471,7 @@ async function startEditorServer(opts) {
       return "missing";
     }
   };
-  const readDoc = async (abs) => RigDocument.parse(JSON.parse(await readFile9(abs, "utf8")));
+  const readDoc = async (abs) => RigDocument.parse(JSON.parse(await readFile10(abs, "utf8")));
   const readDocAt = async (abs) => {
     let v = await version(abs);
     for (let i = 0; i < 3; i++) {
@@ -5283,7 +6492,7 @@ async function startEditorServer(opts) {
   const watchers = /* @__PURE__ */ new Map();
   function ensureWatch(abs) {
     if (watchers.has(abs)) return;
-    const entry = { w: fsWatch(dirname7(abs), { persistent: false }, (_e, file) => {
+    const entry = { w: fsWatch(dirname9(abs), { persistent: false }, (_e, file) => {
       if (file && file !== basename5(abs)) return;
       schedule();
     }), last: "" };
@@ -5313,16 +6522,16 @@ data: ${JSON.stringify({ version: v })}
   async function listRigs() {
     const out = [];
     const walk = async (dir) => {
-      for (const e of await readdir3(dir, { withFileTypes: true })) {
+      for (const e of await readdir5(dir, { withFileTypes: true })) {
         if (e.isDirectory()) {
-          if (!SKIP.has(e.name)) await walk(join8(dir, e.name));
+          if (!SKIP.has(e.name)) await walk(join10(dir, e.name));
           continue;
         }
         if (e.name !== "rig.json") continue;
-        const abs = join8(dir, e.name);
+        const abs = join10(dir, e.name);
         let name = "?";
         try {
-          name = String(JSON.parse(await readFile9(abs, "utf8")).meta?.name ?? "?");
+          name = String(JSON.parse(await readFile10(abs, "utf8")).meta?.name ?? "?");
         } catch {
         }
         out.push({ rig: relative3(root3, abs).split(sep).join("/"), name, mtimeMs: (await stat3(abs)).mtimeMs });
@@ -5332,9 +6541,9 @@ data: ${JSON.stringify({ version: v })}
     return out.sort((a, b) => b.mtimeMs - a.mtimeMs);
   }
   async function listFiles(rigAbs) {
-    const dir = dirname7(rigAbs), out = [];
-    for (const e of (await readdir3(dir, { withFileTypes: true })).filter((e2) => e2.isFile() && /\.png$/i.test(e2.name)).sort((a, b) => a.name.localeCompare(b.name))) {
-      const fh = await open(join8(dir, e.name));
+    const dir = dirname9(rigAbs), out = [];
+    for (const e of (await readdir5(dir, { withFileTypes: true })).filter((e2) => e2.isFile() && /\.png$/i.test(e2.name)).sort((a, b) => a.name.localeCompare(b.name))) {
+      const fh = await open(join10(dir, e.name));
       try {
         const head = Buffer.alloc(24);
         const { bytesRead } = await fh.read(head, 0, 24, 0);
@@ -5369,13 +6578,13 @@ data: ${JSON.stringify({ version: v })}
       }
       if (url.pathname.startsWith("/api/")) return await api(url, req, res);
       const STATIC = /* @__PURE__ */ new Set(["/editor.html", "/dist/editor.js", "/dist/editor.js.map", "/dist/editor.css", "/dist/editor.css.map"]);
-      const abs = url.pathname.startsWith("/rig/") ? inside(decodeURIComponent(url.pathname.slice(5))) : STATIC.has(url.pathname) ? join8(assets, url.pathname) : void 0;
+      const abs = url.pathname.startsWith("/rig/") ? inside(decodeURIComponent(url.pathname.slice(5))) : STATIC.has(url.pathname) ? join10(assets, url.pathname) : void 0;
       if (!abs) {
         res.writeHead(403);
         return res.end("forbidden");
       }
       try {
-        const data = await readFile9(abs);
+        const data = await readFile10(abs);
         res.writeHead(200, { "content-type": TYPES[extname2(abs)] ?? "application/octet-stream" });
         res.end(data);
       } catch {
@@ -5451,8 +6660,8 @@ data: ${JSON.stringify({ version: v })}
       const abs = inside(rig);
       if (!abs) return json(res, 403, { isError: true, text: "rig outside root" });
       if (await stat3(abs).then(() => true, () => false)) return json(res, 409, { isError: true, text: `ERROR: ${rig} already exists \u2014 open it, or pick another directory` });
-      await mkdir5(dirname7(abs), { recursive: true });
-      const r = await callTool("rig_create", { path: abs, name: name ?? basename5(dirname7(abs)), width: width ?? 640, height: height ?? 700 });
+      await mkdir7(dirname9(abs), { recursive: true });
+      const r = await callTool("rig_create", { path: abs, name: name ?? basename5(dirname9(abs)), width: width ?? 640, height: height ?? 700 });
       ensureWatch(abs);
       return json(res, r.isError ? 400 : 200, { text: r.text, doc: r.doc, isError: r.isError, version: await version(abs) });
     }
@@ -5467,7 +6676,7 @@ data: ${JSON.stringify({ version: v })}
       const name = url.searchParams.get("name") ?? "";
       if (!/^[A-Za-z0-9._-]+\.png$/i.test(name) || name.startsWith(".")) return json(res, 400, { isError: true, text: `ERROR: bad file name "${name}" \u2014 letters, digits, . _ - and a .png extension` });
       if (!String(req.headers["content-type"] ?? "").toLowerCase().startsWith("image/png")) return json(res, 415, { isError: true, text: "ERROR: upload needs content-type: image/png" });
-      const target = join8(dirname7(abs), name);
+      const target = join10(dirname9(abs), name);
       if (!inside(relative3(root3, target))) return json(res, 403, { isError: true, text: "file outside root" });
       if (await stat3(target).then(() => true, () => false)) return json(res, 409, { isError: true, text: `ERROR: ${name} already exists next to the rig \u2014 rename the file` });
       const data = await bytes(req, UPLOAD_MAX);