@energy8platform/golem 0.3.0 → 0.6.0

package/dist/lib/tools.js

@@ -1,6 +1,6 @@
 // src/rig-api.ts
 import { z as z3 } from "zod";
-import { readFile as readFile9, writeFile as writeFile7, stat as stat2 } from "node:fs/promises";
+import { readFile as readFile9, writeFile as writeFile7, stat as stat2, mkdir as mkdir6, readdir as readdir4 } from "node:fs/promises";
 import { dirname as dirname8, join as join9, relative as relative2, isAbsolute } from "node:path";
 
 // src/rig-io.ts
@@ -216,7 +216,9 @@ var PathAttachment = z.object({
   /** curve lengths for constant-speed positioning */
   lengths: z.array(z.number()).default([]),
   closed: z.boolean().default(false),
-  constantSpeed: z.boolean().default(true)
+  constantSpeed: z.boolean().default(true),
+  /** Spine-style active clipping span in the posed draw order; end slot is inclusive. */
+  clipping: z.object({ end: Id.optional() }).optional()
 });
 var Attachment = z.discriminatedUnion("type", [RegionAttachment, MeshAttachment, PathAttachment]);
 var IkConstraint = z.object({
@@ -285,10 +287,13 @@ var Key = z.object({
   t: z.number().nonnegative(),
   v: KeyValue,
   /** easing INTO the next key */
-  ease: Ease.default("ease_in_out")
+  ease: Ease.default("ease_in_out"),
+  /** Optional independent easing for numeric-array components (for example Spine RGBA curves). */
+  componentEase: z.array(Ease).min(1).optional()
 });
 var Interpolation = { interpolation: z.enum(["segment", "pchip"]).optional() };
 var Track = z.discriminatedUnion("target", [
+  z.object({ target: z.literal("control"), id: Id, prop: z.literal("value"), ...Interpolation, keys: z.array(Key).min(1) }),
   z.object({ target: z.literal("bone"), id: Id, prop: BoneProp, ...Interpolation, keys: z.array(Key).min(1) }),
   z.object({ target: z.literal("slot"), id: Id, prop: SlotProp, ...Interpolation, keys: z.array(Key).min(1) }),
   z.object({ target: z.literal("deform"), id: Id, prop: DeformProp, ...Interpolation, keys: z.array(Key).min(1) }),
@@ -311,6 +316,25 @@ var Animation = z.object({
   /** if generated from a preset — keep params so the agent can re-tune instead of re-keying */
   preset: z.object({ name: z.string(), params: z.record(z.unknown()) }).optional()
 });
+var RigControl = z.object({
+  id: Id,
+  label: z.string().optional(),
+  min: z.number().finite(),
+  max: z.number().finite(),
+  default: z.number().finite()
+}).strict();
+var ControlValues = z.array(z.union([z.number().finite(), z.array(z.number().finite()).min(1)])).min(2);
+var ControlChannel = z.discriminatedUnion("target", [
+  z.object({ target: z.literal("bone"), id: Id, prop: BoneProp, values: ControlValues }).strict(),
+  z.object({ target: z.literal("slot"), id: Id, prop: z.literal("alpha"), values: ControlValues }).strict(),
+  z.object({ target: z.literal("deform"), id: Id, prop: z.literal("vertices"), values: ControlValues }).strict()
+]);
+var ControlBinding = z.object({
+  id: Id,
+  axes: z.array(z.object({ control: Id, keys: z.array(z.number().finite()).min(2).max(32) }).strict()).min(1).max(2),
+  /** Flattened grid, first axis varies fastest. Linear / bilinear interpolation. */
+  channels: z.array(ControlChannel).min(1)
+}).strict();
 var Reference = z.object({
   src: z.string(),
   opacity: z.number().min(0).max(1).default(0.5),
@@ -336,7 +360,9 @@ var RigSchema = z.object({
   ik: z.array(IkConstraint).default([]),
   transform: z.array(TransformConstraint).default([]),
   path: z.array(PathConstraint).default([]),
-  animations: z.array(Animation)
+  animations: z.array(Animation),
+  controls: z.array(RigControl).optional(),
+  controlBindings: z.array(ControlBinding).optional()
 });
 var RigDocument = z.preprocess((input) => {
   const v = input?.version;
@@ -411,6 +437,8 @@ function validate(doc) {
   dup(doc.ik, "ik");
   dup(doc.transform, "transform");
   dup(doc.path, "path");
+  dup(doc.controls ?? [], "control");
+  dup(doc.controlBindings ?? [], "control binding");
   const bones = new Set(doc.bones.map((b) => b.id));
   const assets = new Map(doc.assets.map((a) => [a.id, a]));
   const slots = new Set(doc.slots.map((s) => s.id));
@@ -448,6 +476,10 @@ function validate(doc) {
       else if (a.slot !== s.id) errs.push(`slot "${s.id}": attachment "${s.attachment}" belongs to slot "${a.slot}"`);
     }
   }
+  for (const a of doc.attachments) if (a.type === "path" && a.clipping) {
+    if (!a.closed) errs.push(`attachment "${a.id}": clipping path must be closed`);
+    if (a.clipping.end && !slots.has(a.clipping.end)) errs.push(`attachment "${a.id}": unknown clipping end slot "${a.clipping.end}"`);
+  }
   const vertexCount2 = (a) => {
     if (a.type === "region") return 4;
     if (a.type === "mesh") return a.uvs.length / 2;
@@ -485,20 +517,59 @@ function validate(doc) {
     for (const b of c.bones) if (!bones.has(b)) errs.push(`path "${c.id}": unknown bone "${b}"`);
     if (!slots.has(c.target)) errs.push(`path "${c.id}": unknown target slot "${c.target}"`);
   }
+  const controls = new Map((doc.controls ?? []).map((c) => [c.id, c]));
+  const driven = /* @__PURE__ */ new Set();
+  for (const c of controls.values()) if (!(c.min < c.max && c.default >= c.min && c.default <= c.max))
+    errs.push(`control "${c.id}": require min < max and default within range`);
+  for (const b of doc.controlBindings ?? []) {
+    const prefix = `control binding "${b.id}"`;
+    if (new Set(b.axes.map((a) => a.control)).size !== b.axes.length) errs.push(`${prefix}: axes must use different controls`);
+    for (const axis of b.axes) {
+      const c = controls.get(axis.control);
+      if (!c) errs.push(`${prefix}: unknown control "${axis.control}"`);
+      else if (axis.keys[0] !== c.min || axis.keys.at(-1) !== c.max) errs.push(`${prefix}: keys must span the control's full range`);
+      if (axis.keys.some((v, i) => i > 0 && v <= axis.keys[i - 1])) errs.push(`${prefix}: keys must be strictly increasing`);
+    }
+    const count = b.axes.reduce((n, a) => n * a.keys.length, 1);
+    for (const ch of b.channels) {
+      const key = `${ch.target}.${ch.id}.${ch.prop}`;
+      if (driven.has(key)) errs.push(`${prefix}: channel ${key} already owned by a binding`);
+      driven.add(key);
+      if (ch.values.length !== count) errs.push(`${prefix}: ${key} needs ${count} grid values`);
+      if (ch.target === "deform") {
+        const att = attachments.get(ch.id);
+        if (!att || att.type === "region") errs.push(`${prefix}: vertices need a mesh or path attachment`);
+        else {
+          const n = att.weights ? att.weights.reduce((s, a) => s + a.length * 2, 0) : att.vertices.length;
+          if (ch.values.some((v) => !Array.isArray(v) || v.length !== n)) errs.push(`${prefix}: ${key} needs arrays of ${n} offsets`);
+        }
+      } else {
+        if (!(ch.target === "bone" ? bones : slots).has(ch.id)) errs.push(`${prefix}: unknown ${ch.target} "${ch.id}"`);
+        if (ch.values.some((v) => typeof v !== "number")) errs.push(`${prefix}: ${key} needs numeric values`);
+        if (ch.target === "slot" && ch.values.some((v) => typeof v === "number" && (v < 0 || v > 1))) errs.push(`${prefix}: alpha must be in 0..1`);
+      }
+    }
+  }
   for (const a of doc.animations) {
     const tracks = /* @__PURE__ */ new Set();
     for (const t of a.tracks) {
       const tid = trackId(t);
       if (tracks.has(tid)) errs.push(`animation "${a.id}": duplicate track ${tid}`);
       tracks.add(tid);
-      const known = t.target === "bone" ? bones.has(t.id) : t.target === "slot" ? slots.has(t.id) : t.target === "deform" ? attachments.has(t.id) : t.target === "ik" ? iks.has(t.id) : t.target === "transform" ? transforms.has(t.id) : t.target === "path" ? paths.has(t.id) : true;
+      if (driven.has(tid)) errs.push(`animation "${a.id}": ${tid} is controlled by a binding; animate its control instead`);
+      const known = t.target === "bone" ? bones.has(t.id) : t.target === "slot" ? slots.has(t.id) : t.target === "deform" ? attachments.has(t.id) : t.target === "ik" ? iks.has(t.id) : t.target === "transform" ? transforms.has(t.id) : t.target === "path" ? paths.has(t.id) : t.target === "control" ? controls.has(t.id) : true;
       if (!known) errs.push(`animation "${a.id}": unknown ${t.target} "${t.id}"`);
       const bound = t.target === "deform" ? DEFORM_BOUNDS[t.prop] : void 0;
       const att = t.target === "deform" ? attachments.get(t.id) : void 0;
       let prev = -1;
       for (const k of t.keys) {
+        if (k.componentEase && (!Array.isArray(k.v) || !k.v.every((v) => typeof v === "number") || k.componentEase.length !== k.v.length)) errs.push(`animation "${a.id}" ${tid}: componentEase must match the numeric-array value length`);
         if (k.t <= prev && prev >= 0) errs.push(`animation "${a.id}" ${tid}: keys not strictly increasing`);
         if (k.t > a.duration) errs.push(`animation "${a.id}" ${tid}: key at ${k.t}s exceeds duration`);
+        if (t.target === "control") {
+          const c = controls.get(t.id);
+          if (typeof k.v !== "number" || !Number.isFinite(k.v) || c && (k.v < c.min || k.v > c.max)) errs.push(`animation "${a.id}" ${tid}: control key outside its finite range`);
+        }
         if (t.target === "slot" && t.prop === "attachment") {
           if (k.v !== null && typeof k.v !== "string") errs.push(`animation "${a.id}" ${tid}: attachment key must be an attachment id or null`);
           else if (typeof k.v === "string") {
@@ -537,6 +608,65 @@ function parse(input) {
   return doc;
 }
 
+// src/rig-controls.ts
+function controlPose(doc, values2) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [id, value] of Object.entries(values2)) {
+    const c = doc.controls?.find((c2) => c2.id === id);
+    if (!c) throw new Error(`unknown control "${id}"`);
+    if (!Number.isFinite(value)) throw new Error(`control "${id}" must be finite`);
+    out.set(`control:${id}:value`, Math.max(c.min, Math.min(c.max, value)));
+  }
+  return out;
+}
+function bracket(keys, value) {
+  let i = 0;
+  while (i < keys.length - 2 && value > keys[i + 1]) i++;
+  return [i, Math.max(0, Math.min(1, (value - keys[i]) / (keys[i + 1] - keys[i])))];
+}
+function sampleBinding(binding, values2) {
+  const [x, u] = bracket(binding.axes[0].keys, values2[0]);
+  const [y, v] = binding.axes[1] ? bracket(binding.axes[1].keys, values2[1]) : [0, 0];
+  const width = binding.axes[0].keys.length, a = y * width + x;
+  const mix = (a2, b, u2) => a2 + (b - a2) * u2;
+  return binding.channels.map((ch) => {
+    const read = (i, j2) => j2 === void 0 ? ch.values[i] : ch.values[i][j2];
+    const at = (j2) => {
+      const top = mix(read(a, j2), read(a + 1, j2), u);
+      return binding.axes[1] ? mix(top, mix(read(a + width, j2), read(a + width + 1, j2), u), v) : top;
+    };
+    return Array.isArray(ch.values[0]) ? ch.values[0].map((_, j2) => at(j2)) : at();
+  });
+}
+function resolveControls(doc, input) {
+  if (!doc.controlBindings?.length) return input;
+  const out = new Map(input), controls = new Map(doc.controls?.map((c) => [c.id, c]));
+  for (const b of doc.controlBindings) {
+    const values2 = b.axes.map((axis) => {
+      const c = controls.get(axis.control);
+      const value = input.get(`control:${c.id}:value`) ?? c.default;
+      if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`control "${c.id}" must be finite`);
+      return Math.max(c.min, Math.min(c.max, value));
+    });
+    const sampled2 = sampleBinding(b, values2);
+    b.channels.forEach((ch, i) => out.set(`${ch.target}:${ch.id}:${ch.prop}`, sampled2[i]));
+  }
+  return out;
+}
+function controlCases(doc, probes) {
+  let cases = [{ label: "default", values: {} }];
+  if (!Object.keys(probes).length) throw new Error("select controls and sample values for the sweep");
+  for (const [id, values2] of Object.entries(probes)) {
+    const c = doc.controls?.find((c2) => c2.id === id);
+    if (!c) throw new Error(`unknown control "${id}"`);
+    if (!values2.length || values2.some((v) => !Number.isFinite(v) || v < c.min || v > c.max) || new Set(values2).size !== values2.length)
+      throw new Error(`control "${id}": probes must be unique finite values inside its range`);
+    if (cases.length * values2.length > 256) throw new Error("control sweep exceeds 256 poses; choose a smaller grid");
+    cases = cases.flatMap((p) => values2.map((v) => ({ label: p.label === "default" ? `${id}=${v}` : `${p.label}, ${id}=${v}`, values: { ...p.values, [id]: v } })));
+  }
+  return cases;
+}
+
 // src/rig-anim.ts
 var DEG2 = Math.PI / 180;
 var named = {
@@ -611,8 +741,8 @@ function sample(track, t, loop = false) {
   }
   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);
+    const phase = (t - a.t) / (b.t - a.t), av = a.v, bv = b.v;
+    return av.map((v, k) => v + ((bv[k] ?? v) - v) * ease(a.componentEase?.[k] ?? a.ease)(phase));
   }
   return a.v;
 }
@@ -640,6 +770,7 @@ function blendPoses(from, to, w, restOf) {
 }
 function restValue(doc, key) {
   const [target, id, prop] = key.split(":");
+  if (target === "control") return doc.controls?.find((c) => c.id === id)?.default ?? 0;
   if (target === "bone") return doc.bones.find((b) => b.id === id).transform[prop];
   if (target === "slot") {
     const s = doc.slots.find((s2) => s2.id === id);
@@ -703,6 +834,13 @@ function boneWorldOf(bone, s, parent) {
   if (!parent) return local;
   if (bone.inherit === "normal") return mul(parent, local);
   const [tx, ty] = apply(parent, s.x, s.y);
+  if (bone.inherit === "noScale" || bone.inherit === "noScaleOrReflection") {
+    const r = s.rotation * DEG2, x = parent.a * Math.cos(r) + parent.c * Math.sin(r), y = parent.b * Math.cos(r) + parent.d * Math.sin(r);
+    const length = Math.hypot(x, y), a = length > 1e-5 ? x / length : x, b = length > 1e-5 ? y / length : y;
+    const sign = bone.inherit === "noScale" && parent.a * parent.d - parent.b * parent.c < 0 ? -1 : 1;
+    const basis3 = { a, b, c: -b * sign, d: a * sign, tx: 0, ty: 0 };
+    return { ...mul(basis3, affineOf(0, 0, 0, s.scaleX, s.scaleY, s.shearX, s.shearY)), tx, ty };
+  }
   return { ...mul(inheritedParentLinear(bone, parent), { ...local, tx: 0, ty: 0 }), tx, ty };
 }
 var orderCache = /* @__PURE__ */ new WeakMap();
@@ -735,18 +873,20 @@ var localOf = (doc, pose, b) => {
     shearY: num(pose, pk("bone", id, "shearY"), r.shearY)
   };
 };
-function updateSubtree(skel, root2) {
+function updateSubtree(skel, root2, includeRoot = true) {
   const doc = skel.doc;
   const kids = /* @__PURE__ */ new Map();
   for (const b of doc.bones) if (b.parent) (kids.get(b.parent) ?? kids.set(b.parent, []).get(b.parent)).push(b);
-  const stack = [root2];
+  const stack = includeRoot ? [root2] : (kids.get(root2) ?? []).map((b) => b.id);
   while (stack.length) {
     const id = stack.pop(), b = boneOf(doc, id), st = skel.bones.get(id);
     st.world = boneWorldOf(b, st, b.parent ? skel.bones.get(b.parent).world : void 0);
     for (const k of kids.get(id) ?? []) stack.push(k.id);
   }
 }
-function evaluate(doc, pose) {
+function evaluate(doc, pose, modifiers) {
+  pose = resolveControls(doc, pose);
+  if (modifiers) for (const modify of modifiers) pose = modify(new Map(pose));
   const skel = { doc, pose, bones: /* @__PURE__ */ new Map(), attachment: /* @__PURE__ */ new Map() };
   for (const b of boneOrder(doc)) {
     const s = localOf(doc, pose, b);
@@ -980,7 +1120,8 @@ function applyTransformConstraint(skel, c) {
   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;
+  const handedness = tw.a * tw.d - tw.b * tw.c < 0 ? -1 : 1;
+  const offsetRotation = c.rotation * DEG2 * (c.local ? 1 : handedness), offsetShearY = c.shearY * DEG2 * (c.local ? 1 : handedness);
   for (const id of c.bones) {
     const b = boneOf(skel.doc, id), st = skel.bones.get(id);
     if (c.local) {
@@ -1142,6 +1283,7 @@ function applyPathConstraint(skel, c) {
   const position = cnum(skel, "path", c.id, "position", c.position), spacing = cnum(skel, "path", c.id, "spacing", c.spacing);
   const tangents = c.rotateMode === "tangent", scale = c.rotateMode === "chainScale";
   const bones = c.bones.map((id) => ({ b: boneOf(skel.doc, id), st: skel.bones.get(id) }));
+  const inputWorlds = bones.map(({ st }) => ({ ...st.world }));
   const spacesCount = tangents ? bones.length : bones.length + 1;
   const spaces = new Array(spacesCount).fill(0), worldLengths = [];
   let sum = 0;
@@ -1176,9 +1318,10 @@ function applyPathConstraint(skel, c) {
     if (tw.a * tw.d - tw.b * tw.c < 0) offsetRotation = -offsetRotation;
   }
   let boneX = samples[0].x, boneY = samples[0].y;
+  const solvedWorlds = /* @__PURE__ */ new Map();
   for (let i = 0; i < bones.length; i++) {
     const { b, st } = bones[i];
-    let w = { ...st.world };
+    let w = { ...inputWorlds[i] };
     w.tx += (boneX - w.tx) * mixX;
     w.ty += (boneY - w.ty) * mixY;
     const next = samples[i + 1] ?? { x: 0, y: 0, angle: 0 };
@@ -1208,7 +1351,11 @@ function applyPathConstraint(skel, c) {
       const cos = Math.cos(r), sin = Math.sin(r);
       w = { a: cos * a - sin * bb, b: sin * a + cos * bb, c: cos * cc - sin * d, d: sin * cc + cos * d, tx: w.tx, ty: w.ty };
     }
-    setEffectiveWorld(skel, b, st, w);
+    solvedWorlds.set(b.id, w);
+  }
+  for (const b of boneOrder(skel.doc)) {
+    const world = solvedWorlds.get(b.id);
+    if (world) setEffectiveWorld(skel, b, skel.bones.get(b.id), world);
   }
 }
 function measuredPathLength(points, closed, lengths, constantSpeed) {
@@ -1237,9 +1384,14 @@ function inheritedParentLinear(bone, parent) {
     case "onlyTranslation":
       return { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 };
     case "noRotationOrReflection": {
-      const lenX = Math.hypot(parent.a, parent.b) || 1;
+      const lenX = Math.hypot(parent.a, parent.b);
       const det = parent.a * parent.d - parent.b * parent.c;
-      return { a: lenX, b: 0, c: 0, d: Math.abs(det) / lenX, tx: 0, ty: 0 };
+      if (lenX * lenX <= 1e-4) {
+        const lenY = Math.hypot(parent.c, parent.d), ux2 = lenY ? parent.c / lenY : 0, uy2 = lenY ? parent.d / lenY : 0;
+        return { a: lenY * ux2 * ux2, b: lenY * ux2 * uy2, c: lenY * ux2 * uy2, d: lenY * uy2 * uy2, tx: 0, ty: 0 };
+      }
+      const ux = parent.a / lenX, uy = parent.b / lenX, sy = Math.abs(det) / lenX;
+      return { a: lenX * ux * ux + sy * uy * uy, b: (lenX - sy) * ux * uy, c: (lenX - sy) * ux * uy, d: lenX * uy * uy + sy * ux * ux, tx: 0, ty: 0 };
     }
     case "noScale":
     case "noScaleOrReflection": {
@@ -1265,7 +1417,16 @@ function setEffectiveWorld(skel, bone, st, world) {
   st.scaleY = Math.hypot(lin.c, lin.d);
   st.shearX = 0;
   st.shearY = shortest(Math.atan2(lin.d, lin.c) / DEG2 - st.rotation - 90);
-  updateSubtree(skel, bone.id);
+  if (parent && (bone.inherit === "noScale" || bone.inherit === "noScaleOrReflection")) {
+    const direction = mul(invert({ ...parent, tx: 0, ty: 0 }), { ...world, tx: 0, ty: 0 });
+    st.rotation = Math.atan2(direction.b, direction.a) / DEG2;
+    st.scaleX = Math.hypot(world.a, world.b);
+    st.scaleY = Math.hypot(world.c, world.d);
+    const sign = bone.inherit === "noScale" && parent.a * parent.d - parent.b * parent.c < 0 ? -1 : 1;
+    st.shearY = shortest((Math.atan2(world.d, world.c) - Math.atan2(world.b, world.a)) / DEG2 * sign - 90);
+  }
+  st.world = world;
+  updateSubtree(skel, bone.id, false);
 }
 function attachmentWorldVertices(skel, slotId, att) {
   const deform = skel.pose.get(pk("deform", att.id, "vertices"));
@@ -1972,6 +2133,9 @@ function updateBone(doc, id, patch) {
   const i = doc.bones.findIndex((b) => b.id === id);
   if (i < 0) throw new Error(`unknown bone "${id}"`);
   const cur = doc.bones[i];
+  for (const b of doc.controlBindings ?? []) for (const ch of b.channels)
+    if (ch.target === "bone" && ch.id === id && patch.transform?.[ch.prop] !== void 0)
+      throw new Error(`bone "${id}" ${ch.prop} is controlled by "${b.id}"; edit its keyforms`);
   const { parent, ...rest } = patch;
   const next = RigSchema.shape.bones.element.parse({
     ...cur,
@@ -2004,6 +2168,11 @@ function patchDrawOrder(doc, fn) {
   return { ...doc, animations: doc.animations.map((a) => ({ ...a, tracks: a.tracks.map((t) => t.target !== "drawOrder" ? t : { ...t, keys: t.keys.map((k) => ({ ...k, v: fn(k.v) })) }) })) };
 }
 function setSlot(doc, slot) {
+  if (slot.alpha !== void 0) {
+    for (const b of doc.controlBindings ?? [])
+      if (b.channels.some((ch) => ch.target === "slot" && ch.id === slot.id && ch.prop === "alpha"))
+        throw new Error(`slot "${slot.id}" alpha is controlled by "${b.id}"; edit its keyforms`);
+  }
   const cur = doc.slots.find((s) => s.id === slot.id);
   if (cur && slot.bone && slot.bone !== cur.bone) doc = rebindSlot(doc, slot.id, slot.bone).doc;
   const base = doc.slots.find((s) => s.id === slot.id);
@@ -2016,7 +2185,7 @@ function removeSlot(doc, id) {
   return patchDrawOrder({
     ...doc,
     slots: doc.slots.filter((s) => s.id !== id).map((s) => gone.has(s.clip ?? "") ? { ...s, clip: void 0 } : s),
-    attachments: doc.attachments.filter((a) => a.slot !== id),
+    attachments: doc.attachments.filter((a) => a.slot !== id).map((a) => a.type === "path" && a.clipping?.end === id ? { ...a, clipping: {} } : a),
     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((s) => s !== id));
 }
@@ -2378,6 +2547,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;
@@ -2411,7 +2581,7 @@ function rename2(doc, kind, id, to) {
       return {
         ...doc,
         slots: doc.slots.map((s) => ({ ...s, id: sub(s.id) })),
-        attachments: doc.attachments.map((a) => ({ ...a, slot: sub(a.slot) })),
+        attachments: doc.attachments.map((a) => ({ ...a, slot: sub(a.slot), ...a.type === "path" && a.clipping?.end ? { clipping: { end: sub(a.clipping.end) } } : {} })),
         path: doc.path.map((c) => ({ ...c, target: sub(c.target) }))
       };
     }
@@ -2459,6 +2629,8 @@ function describeAttachment(doc, att) {
 }
 function describe(doc, opts = {}) {
   const lines = [`${doc.meta.name} ${doc.meta.width}x${doc.meta.height}`];
+  for (const c of doc.controls ?? []) lines.push(`control ${c.id}: [${c.min}..${c.max}], default ${c.default}${c.label ? ` (${c.label})` : ""}`);
+  for (const b of doc.controlBindings ?? []) lines.push(`keyforms ${b.id}: ${b.axes.map((a) => `${a.control}[${a.keys.join(",")}]`).join(" \xD7 ")} \u2192 ${b.channels.map((c) => `${c.target}.${c.id}.${c.prop}`).join(", ")}`);
   if (doc.meta.notes) lines.push(`notes: ${doc.meta.notes}`);
   const kids = (id) => doc.bones.filter((b) => b.parent === id);
   const place = (s) => {
@@ -3158,8 +3330,8 @@ function motionQuality(doc, anim, opts = {}) {
       if (!skel.attachment.get(front) || !skel.attachment.get(back)) continue;
       const visible = (id) => {
         const slot = doc.slots.find((s) => s.id === id);
-        const color = pose.get(pk("slot", id, "color")) ?? colorToArray(slot.color);
-        return Number(pose.get(pk("slot", id, "alpha")) ?? slot.alpha) * color[3] > 0;
+        const color = skel.pose.get(pk("slot", id, "color")) ?? colorToArray(slot.color);
+        return Number(skel.pose.get(pk("slot", id, "alpha")) ?? slot.alpha) * color[3] > 0;
       };
       if (!visible(front) || !visible(back)) continue;
       const order = pose.get(pk("drawOrder", "order", "order"));
@@ -3234,6 +3406,7 @@ function checkRig(doc, opts = {}) {
   });
   const W = doc.meta.width, H = doc.meta.height;
   const overflowOf = (pose, slotId, skel) => {
+    pose = skel.pose;
     const pts = slotOutline(doc, pose, slotId, 4, skel);
     if (!pts) return void 0;
     const slot = doc.slots.find((s) => s.id === slotId), alphaV = pose.get(`slot:${slotId}:alpha`);
@@ -3432,6 +3605,7 @@ function checkRig(doc, opts = {}) {
       }
     }
     const vertexKeyed = new Set(a.tracks.filter((t) => t.target === "deform" && t.prop === "vertices").map((t) => t.id));
+    for (const b of doc.controlBindings ?? []) for (const ch of b.channels) if (ch.target === "deform") vertexKeyed.add(ch.id);
     const deformMeshes = meshes.filter((att) => vertexKeyed.has(att.id));
     const bonesMeshes = meshes.filter((att) => !vertexKeyed.has(att.id));
     const meshFolds = /* @__PURE__ */ new Map();
@@ -3768,11 +3942,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);
@@ -4018,6 +4194,9 @@ var Ids = class {
   has(name) {
     return this.map.has(name);
   }
+  reserve(id) {
+    this.used.add(id);
+  }
 };
 var spineToDoc = (x, y, originX, originY) => [x + originX, originY - y];
 var r4 = (v) => Math.round(v * 1e6) / 1e6 + 0;
@@ -4026,6 +4205,7 @@ function importSpine(json, atlasText, opts = {}) {
   const warnings = [];
   const atlas = parseAtlas(atlasText);
   const version = String(json.skeleton?.spine ?? "4.0");
+  if (json.physics?.length) warnings.push(`${json.physics.length} Spine physics constraints are not imported; bake their motion before delivery`);
   const major = parseFloat(version);
   const bounds = { x: json.skeleton?.x ?? 0, y: json.skeleton?.y ?? 0, w: json.skeleton?.width ?? 0, h: json.skeleton?.height ?? 0 };
   const margin = opts.margin ?? 0;
@@ -4033,6 +4213,7 @@ function importSpine(json, atlasText, opts = {}) {
   const toDoc = (x, y) => spineToDoc(x, y, originX, originY);
   const boneIds = new Ids("b_"), slotIds = new Ids("s_"), assetIds = new Ids("a_"), attIds = new Ids("att_"), ikIds = new Ids("ik_"), tcIds = new Ids("tc_"), pcIds = new Ids("pc_"), animIds = new Ids("anim_");
   const ROOT = "origin";
+  boneIds.reserve(ROOT);
   const attachmentIdMap = /* @__PURE__ */ new Map();
   const attachmentId = (slot, name) => {
     const key = `${slot} ${name}`;
@@ -4057,13 +4238,17 @@ function importSpine(json, atlasText, opts = {}) {
     });
   }
   const skins = Array.isArray(json.skins) ? json.skins : Object.entries(json.skins ?? {}).map(([name, attachments2]) => ({ name, attachments: attachments2 }));
+  const selectedSkin = opts.skin ? skins.find((s) => s.name === opts.skin) : skins.find((s) => s.name === "default") ?? skins[0];
+  if (opts.skin && !selectedSkin) throw new Error(`Spine skin "${opts.skin}" not found; available: ${skins.map((s) => s.name).join(", ")}`);
+  const lookupSkins = [selectedSkin, skins.find((s) => s.name === "default")].filter((s, i, list) => s && list.indexOf(s) === i);
+  if (skins.length > 1) warnings.push(`Spine skin "${selectedSkin?.name}" selected; setup and attachment timelines are flattened to this skin with default fallback (no runtime skin switching)`);
   const frameSuffix = (seq, index) => {
-    const n = String((seq.start ?? 0) + index);
+    const n = String((seq.start ?? 1) + index);
     return "0".repeat(Math.max(0, (seq.digits ?? 0) - n.length)) + n;
   };
   const sequences = /* @__PURE__ */ new Map();
   const skinnedName = /* @__PURE__ */ new Map();
-  for (const skin2 of skins) {
+  for (const skin2 of lookupSkins) {
     const prefix = skin2.name === "default" ? "" : `${skin2.name}_`;
     for (const [slotName, atts] of Object.entries(skin2.attachments ?? {}))
       for (const [name, a] of Object.entries(atts)) {
@@ -4072,7 +4257,10 @@ function importSpine(json, atlasText, opts = {}) {
         if (!skinnedName.has(key)) skinnedName.set(key, prefix + name + (seq ? frameSuffix(seq, seq.setupIndex ?? 0) : ""));
       }
   }
-  const attachmentRef = (slot, name) => attachmentId(slot, skinnedName.get(`${slot} ${name}`) ?? name);
+  const attachmentRef = (slot, name) => {
+    const resolved = skinnedName.get(`${slot} ${name}`);
+    return resolved === void 0 ? null : attachmentId(slot, resolved);
+  };
   const spineSlots = json.slots ?? [];
   const slotIndexByName = new Map(spineSlots.map((s, i) => [s.name, i]));
   const blendOf = (b) => b === "additive" ? "add" : b === "multiply" ? "multiply" : b === "screen" ? "screen" : "normal";
@@ -4080,11 +4268,12 @@ function importSpine(json, atlasText, opts = {}) {
     id: slotIds.get(s.name),
     bone: boneIds.get(s.bone),
     z: i,
-    ...s.attachment ? { attachment: attachmentRef(s.name, s.attachment) } : {},
+    ...s.attachment && attachmentRef(s.name, s.attachment) ? { attachment: attachmentRef(s.name, s.attachment) } : {},
     blend: blendOf(s.blend),
     color: hex8(s.color),
     alpha: 1
   }));
+  if (spineSlots.some((s) => s.dark)) warnings.push("Spine setup dark two-color tint is not supported");
   const pageImage = (page2) => typeof opts.pageImage === "function" ? opts.pageImage(page2) : opts.pageImage ?? page2;
   const assets = /* @__PURE__ */ new Map();
   const regionByName = new Map(atlas.regions.map((r) => [r.name, r]));
@@ -4110,6 +4299,7 @@ function importSpine(json, atlasText, opts = {}) {
     return id;
   };
   const attachments = [];
+  const clipDeforms = /* @__PURE__ */ new Map();
   const readVertices = (a, vertexCount2) => {
     const v = a.vertices ?? [];
     if (v.length === vertexCount2 * 2) {
@@ -4130,6 +4320,22 @@ function importSpine(json, atlasText, opts = {}) {
     }
     return { weights };
   };
+  const meshGeometry = (skinName, slot, name, visiting = /* @__PURE__ */ new Set()) => {
+    const key = JSON.stringify([skinName, slot, name]);
+    if (visiting.has(key)) {
+      warnings.push(`linked mesh cycle at "${skinName}/${slot}/${name}" skipped`);
+      return void 0;
+    }
+    const raw = skins.find((s) => s.name === skinName)?.attachments?.[slot]?.[name];
+    if (!raw) {
+      warnings.push(`linked mesh parent "${skinName}/${slot}/${name}" not found`);
+      return void 0;
+    }
+    if (!raw.parent) return raw;
+    visiting.add(key);
+    return meshGeometry(raw.skin ?? "default", slot, raw.parent, visiting);
+  };
+  const inheritedDeform = /* @__PURE__ */ new Map();
   for (const skin2 of skins) {
     const prefix = skin2.name === "default" ? "" : `${skin2.name}_`;
     for (const [slotName, atts] of Object.entries(skin2.attachments ?? {})) {
@@ -4141,7 +4347,7 @@ function importSpine(json, atlasText, opts = {}) {
       for (const [name, a] of Object.entries(atts)) {
         if (a.sequence) {
           sequences.set(`${slotName} ${prefix}${name}`, a.sequence);
-          const base = a.path ?? name;
+          const base = a.path ?? a.name ?? name;
           for (let i = 0; i < (a.sequence.count ?? 0); i++) {
             const suffix = frameSuffix(a.sequence, i), asset = assetFor(base + suffix);
             if (!asset) continue;
@@ -4164,7 +4370,7 @@ function importSpine(json, atlasText, opts = {}) {
         }
         const type = a.type ?? "region", id = attachmentId(slotName, prefix + name);
         if (type === "region") {
-          const asset = assetFor(a.path ?? name);
+          const asset = assetFor(a.path ?? a.name ?? name);
           if (!asset) continue;
           attachments.push({
             id,
@@ -4180,21 +4386,48 @@ function importSpine(json, atlasText, opts = {}) {
             ...a.height ? { height: a.height } : {}
           });
         } else if (type === "mesh" || type === "linkedmesh") {
-          if (type === "linkedmesh") {
-            warnings.push(`linked mesh "${slotName}/${name}" skipped`);
-            continue;
-          }
-          const asset = assetFor(a.path ?? name);
+          const geometry = a.parent ? meshGeometry(skin2.name, slotName, name) : a;
+          if (!geometry) continue;
+          const asset = assetFor(a.path ?? a.name ?? name);
           if (!asset) continue;
-          const n = (a.uvs?.length ?? 0) / 2;
-          attachments.push({ id, slot, type: "mesh", asset, uvs: a.uvs, triangles: a.triangles, ...readVertices(a, n), hull: a.hull ?? 0, ...a.width ? { width: a.width } : {}, ...a.height ? { height: a.height } : {} });
+          const n = (geometry.uvs?.length ?? 0) / 2;
+          attachments.push({ id, slot, type: "mesh", asset, uvs: geometry.uvs, triangles: geometry.triangles, ...readVertices(geometry, n), hull: geometry.hull ?? 0, ...geometry.width ? { width: geometry.width } : {}, ...geometry.height ? { height: geometry.height } : {} });
+          if (a.parent && (a.timelines ?? a.deform ?? true)) {
+            const parentSkin = a.skin ?? "default";
+            inheritedDeform.set(id, attachmentId(slotName, (parentSkin === "default" ? "" : `${parentSkin}_`) + a.parent));
+          }
         } else if (type === "path") {
           attachments.push({ id, slot, type: "path", ...readVertices(a, a.vertexCount ?? 0), lengths: a.lengths ?? [], closed: !!a.closed, constantSpeed: a.constantSpeed ?? true });
+        } else if (type === "clipping") {
+          const data = readVertices(a, a.vertexCount), n = a.vertexCount;
+          const recipes = Array.from({ length: n }, (_, i) => [
+            [[(i + n - 1) % n, 1 / 3], [i, 2 / 3]],
+            [[i, 1]],
+            [[i, 2 / 3], [(i + 1) % n, 1 / 3]]
+          ]).flat();
+          let geometry;
+          if (data.weights) {
+            const starts = [];
+            let offset = 0;
+            for (const list of data.weights) {
+              starts.push(offset);
+              offset += list.length * 2;
+            }
+            const mapping = recipes.flatMap((recipe) => recipe.flatMap(([index]) => data.weights[index].map((_, k) => starts[index] + k * 2)));
+            geometry = { weights: recipes.map((recipe) => recipe.flatMap(([index, factor]) => data.weights[index].map((inf) => ({ ...inf, w: inf.w * factor })))) };
+            clipDeforms.set(id, (offsets) => mapping.flatMap((index) => [offsets[index] ?? 0, offsets[index + 1] ?? 0]));
+          } else {
+            const expand = (values2) => recipes.flatMap((recipe) => [0, 1].map((axis) => recipe.reduce((sum, [index, factor]) => sum + (values2[index * 2 + axis] ?? 0) * factor, 0)));
+            geometry = { vertices: expand(data.vertices) };
+            clipDeforms.set(id, expand);
+          }
+          attachments.push({ id, slot, type: "path", ...geometry, closed: true, clipping: { ...a.end ? { end: slotIds.get(a.end) } : {} } });
         } else warnings.push(`attachment "${slotName}/${name}" of type ${type} skipped`);
       }
     }
   }
-  const ik = (json.ik ?? []).map((c) => ({
+  const activeConstraint = (kind, c) => !c.skin || lookupSkins.some((s) => s[kind]?.includes(c.name));
+  const ik = (json.ik ?? []).filter((c) => activeConstraint("ik", c)).map((c) => ({
     id: ikIds.get(c.name),
     order: c.order ?? 0,
     bones: c.bones.map((b) => boneIds.get(b)),
@@ -4207,7 +4440,7 @@ function importSpine(json, atlasText, opts = {}) {
     stretch: !!c.stretch,
     uniform: !!c.uniform
   }));
-  const transform = (json.transform ?? []).map((c) => ({
+  const transform = (json.transform ?? []).filter((c) => activeConstraint("transform", c)).map((c) => ({
     id: tcIds.get(c.name),
     order: c.order ?? 0,
     bones: c.bones.map((b) => boneIds.get(b)),
@@ -4227,7 +4460,7 @@ function importSpine(json, atlasText, opts = {}) {
     mixScaleY: c.mixScaleY ?? c.mixScaleX ?? c.scaleMix ?? 1,
     mixShearY: c.mixShearY ?? c.shearMix ?? 1
   }));
-  const path = (json.path ?? []).map((c) => ({
+  const path = (json.path ?? []).filter((c) => activeConstraint("path", c)).map((c) => ({
     id: pcIds.get(c.name),
     order: c.order ?? 0,
     bones: c.bones.map((b) => boneIds.get(b)),
@@ -4262,7 +4495,21 @@ function importSpine(json, atlasText, opts = {}) {
     for (let i = 0; i < frames.length; i++) {
       const f = frames[i], next = frames[i + 1], t = f.time ?? 0;
       const ease2 = next ? easeOf(f.curve, comp, t, next.time ?? 0, f[field] ?? def, next[field] ?? def) : "linear";
-      keys.push({ t: r4(t), v: r4(abs(f[field] ?? def)), ease: ease2 });
+      const curve = major >= 4 && Array.isArray(f.curve) ? f.curve.slice(comp * 4, comp * 4 + 4) : [];
+      const value = f[field] ?? def;
+      if (next && value === (next[field] ?? def) && curve.length === 4 && (curve[1] !== value || curve[3] !== value)) {
+        const cubic = (p0, p1, p2, p3, u) => (1 - u) ** 3 * p0 + 3 * (1 - u) ** 2 * u * p1 + 3 * (1 - u) * u * u * p2 + u ** 3 * p3;
+        const inner = Array.from({ length: 9 }, (_, k) => {
+          const u = (k + 1) / 10;
+          return { t: r4(cubic(t, curve[0], curve[2], next.time ?? 0, u)), v: r4(abs(cubic(value, curve[1], curve[3], value, u))), ease: "linear" };
+        });
+        if (inner.every((k, i2) => k.t > (i2 ? inner[i2 - 1].t : t) && k.t < (next.time ?? 0))) {
+          keys.push({ t: r4(t), v: r4(abs(value)), ease: "linear" }, ...inner);
+          continue;
+        }
+        warnings.push(`equal-endpoint ${field} curve at ${t}s has non-monotonic control times and could not be lowered`);
+      }
+      keys.push({ t: r4(t), v: r4(abs(value)), ease: ease2 });
     }
     return keys;
   };
@@ -4273,6 +4520,10 @@ function importSpine(json, atlasText, opts = {}) {
     const seen = (frames) => {
       for (const f of frames) duration = Math.max(duration, f.time ?? 0);
     };
+    if (a.physics) {
+      warnings.push(`${animName}: Spine physics timelines are not imported`);
+      for (const timelines of Object.values(a.physics)) for (const frames of Object.values(timelines)) seen(frames);
+    }
     for (const [boneName, tl] of Object.entries(a.bones ?? {})) {
       const sb = spineBones[boneIndexByName.get(boneName)];
       if (!sb) {
@@ -4313,19 +4564,22 @@ function importSpine(json, atlasText, opts = {}) {
         if (kind === "attachment") {
           attachmentFrames.set(slotName, frames);
           tracks.push(track("slot", id, "attachment", frames.map((f) => ({ t: r4(f.time ?? 0), v: f.name ? attachmentRef(slotName, f.name) : null, ease: "step" }))));
-        } else if (kind === "rgba" || kind === "color") {
+        } else if (["rgba", "color", "rgb", "rgba2", "rgb2"].includes(kind)) {
+          const setupAlpha = parseInt(hex8(spineSlots[slotIndexByName.get(slotName)].color).slice(7), 16) / 255;
+          const rgbOnly = kind === "rgb" || kind === "rgb2";
           const rgbaOf = (f) => {
-            const c = hex8(f.color);
-            return [0, 2, 4, 6].map((k) => parseInt(c.slice(1 + k, 3 + k), 16) / 255);
+            const c = hex8(f.color ?? f.light);
+            return [0, 2, 4, 6].map((k, i) => i === 3 && rgbOnly ? setupAlpha : parseInt(c.slice(1 + k, 3 + k), 16) / 255);
           };
+          if (kind.endsWith("2")) warnings.push(`${animName}/${slotName}: ${kind} light color imported; dark two-color tint is not supported`);
           tracks.push(track("slot", id, "color", frames.map((f, i) => {
             const rgba = rgbaOf(f), next = frames[i + 1];
-            return { t: r4(f.time ?? 0), v: rgba.map(r4), ease: next ? easeOf(f.curve, 0, f.time ?? 0, next.time ?? 0, rgba[0], rgbaOf(next)[0]) : "linear" };
-          })));
-        } else if (kind === "rgb") {
-          tracks.push(track("slot", id, "color", frames.map((f) => {
-            const c = hex8((f.color ?? "ffffff") + "ff");
-            return { t: r4(f.time ?? 0), v: [0, 2, 4, 6].map((k) => r4(parseInt(c.slice(1 + k, 3 + k), 16) / 255)), ease: "linear" };
+            return {
+              t: r4(f.time ?? 0),
+              v: rgba.map(r4),
+              ease: "linear",
+              ...next ? { componentEase: rgba.map((v, k) => rgbOnly && k === 3 ? "linear" : easeOf(f.curve, k, f.time ?? 0, next.time ?? 0, v, rgbaOf(next)[k])) } : {}
+            };
           })));
         } else if (kind === "alpha") tracks.push(track("slot", id, "alpha", numeric(frames, "value", 1, (v) => v, 0)));
         else warnings.push(`${animName}/${slotName}: ${kind} timeline skipped`);
@@ -4364,15 +4618,30 @@ function importSpine(json, atlasText, opts = {}) {
         warnings.push(`${animName}: deform of unknown attachment ${slotName}/${attName}`);
         continue;
       }
-      const length = att.weights ? 2 * att.weights.reduce((s, l) => s + l.length, 0) : att.vertices?.length ?? 0;
+      const rawClip = skins.find((s) => s.name === skinName)?.attachments?.[slotName]?.[attName];
+      const clipData = clipDeforms.has(id) ? readVertices(rawClip, rawClip.vertexCount) : void 0;
+      const data = clipData ?? att;
+      const length = data.weights ? 2 * data.weights.reduce((s, l) => s + l.length, 0) : data.vertices?.length ?? 0;
       tracks.push(track("deform", id, "vertices", frames.map((f, i) => {
         const full = new Array(length).fill(0);
         const off = f.offset ?? 0, vs = f.vertices ?? [];
         for (let k = 0; k < vs.length; k++) full[off + k] = (k + off) % 2 === 1 ? -vs[k] : vs[k];
         const next = frames[i + 1];
-        return { t: r4(f.time ?? 0), v: full.map(r4), ease: next ? easeOf(f.curve, 0, f.time ?? 0, next.time ?? 0, 0, 1) : "linear" };
+        return { t: r4(f.time ?? 0), v: (clipDeforms.get(id)?.(full) ?? full).map(r4), ease: next ? easeOf(f.curve, 0, f.time ?? 0, next.time ?? 0, 0, 1) : "linear" };
       })));
     }
+    for (let pass = 0; pass < inheritedDeform.size; pass++) {
+      let changed = false;
+      for (const [child, parent] of inheritedDeform) {
+        if (tracks.some((t) => t.target === "deform" && t.id === child)) continue;
+        const source = tracks.find((t) => t.target === "deform" && t.id === parent);
+        if (source) {
+          tracks.push({ ...source, id: child, keys: structuredClone(source.keys) });
+          changed = true;
+        }
+      }
+      if (!changed) break;
+    }
     const drawOrderFrames = a.drawOrder ?? a.draworder;
     if (Array.isArray(drawOrderFrames)) {
       seen(drawOrderFrames);
@@ -4395,20 +4664,25 @@ function importSpine(json, atlasText, opts = {}) {
     for (const [name, frames] of Object.entries(a.ik ?? {})) {
       seen(frames);
       const id = ikIds.get(name);
+      if (!ik.some((c) => c.id === id)) continue;
       tracks.push(track("ik", id, "mix", numeric(frames, "mix", 1, (v) => v, 0)));
       tracks.push(track("ik", id, "softness", numeric(frames, "softness", 0, (v) => v, 1)));
       tracks.push(track("ik", id, "bendPositive", frames.map((f) => ({ t: r4(f.time ?? 0), v: f.bendPositive ?? true ? 0 : 1, ease: "step" }))));
       tracks.push(track("ik", id, "compress", frames.map((f) => ({ t: r4(f.time ?? 0), v: f.compress ? 1 : 0, ease: "step" }))));
       tracks.push(track("ik", id, "stretch", frames.map((f) => ({ t: r4(f.time ?? 0), v: f.stretch ? 1 : 0, ease: "step" }))));
     }
-    const mixTrack = (target, id, frames, prop, old, comp) => track(target, id, prop, frames.map((f, i) => ({
-      t: r4(f.time ?? 0),
-      v: r4(f[prop] ?? f[old] ?? 1),
-      ease: frames[i + 1] ? easeOf(f.curve, comp, f.time ?? 0, frames[i + 1].time ?? 0, f[prop] ?? f[old] ?? 1, frames[i + 1][prop] ?? frames[i + 1][old] ?? 1) : "linear"
-    })));
+    const mixTrack = (target, id, frames, prop, old, comp) => {
+      const value = (f) => f[prop] ?? (prop === "mixY" ? f.mixX : prop === "mixScaleY" ? f.mixScaleX : void 0) ?? f[old] ?? 1;
+      return track(target, id, prop, frames.map((f, i) => ({
+        t: r4(f.time ?? 0),
+        v: r4(value(f)),
+        ease: frames[i + 1] ? easeOf(f.curve, comp, f.time ?? 0, frames[i + 1].time ?? 0, value(f), value(frames[i + 1])) : "linear"
+      })));
+    };
     for (const [name, frames] of Object.entries(a.transform ?? {})) {
       seen(frames);
       const id = tcIds.get(name);
+      if (!transform.some((c) => c.id === id)) continue;
       const props = [["mixRotate", "rotateMix", 0], ["mixX", "translateMix", 1], ["mixY", "translateMix", 2], ["mixScaleX", "scaleMix", 3], ["mixScaleY", "scaleMix", 4], ["mixShearY", "shearMix", 5]];
       for (const [prop, old, comp] of props) tracks.push(mixTrack("transform", id, frames, prop, old, comp));
     }
@@ -4416,6 +4690,7 @@ function importSpine(json, atlasText, opts = {}) {
       const id = pcIds.get(name);
       for (const [kind, frames] of Object.entries(tl)) {
         seen(frames);
+        if (!path.some((c) => c.id === id)) continue;
         if (kind === "position" || kind === "spacing") tracks.push(track("path", id, kind, numeric(frames, "value", 0, (v) => v, 0)));
         else if (kind === "mix") for (const [prop, old, comp] of [["mixRotate", "rotateMix", 0], ["mixX", "translateMix", 1], ["mixY", "translateMix", 2]])
           tracks.push(mixTrack("path", id, frames, prop, old, comp));
@@ -4578,21 +4853,27 @@ async function importSpineProject(opts) {
   const atlasPath = opts.atlas ?? await firstExisting([stem + ".atlas", stem + ".atlas.txt"], "atlas");
   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 = 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");
+  if (!pages.length) throw new Error("atlas has no pages");
+  if (opts.image && pages.length !== 1) throw new Error("image override requires a single-page atlas; multi-page atlases resolve each named page beside the atlas");
   const rigDir = dirname6(opts.rigPath);
-  let pngPath = imagePath;
-  if (extname(imagePath).toLowerCase() === ".ktx2") {
-    pngPath = join8(rigDir, basename4(imagePath).replace(/\.ktx2$/i, ".png"));
-    if (!await exists(pngPath)) {
-      const { png } = await ktx2ToPng(new Uint8Array(await readFile7(imagePath)));
-      await writeFile5(pngPath, png);
+  const pagePaths = /* @__PURE__ */ new Map();
+  for (const page2 of pages) {
+    const pageStem = join8(dirname6(atlasPath), page2.name.replace(/\.[a-z0-9]+$/i, ""));
+    const imagePath = opts.image ?? await firstExisting([join8(dirname6(atlasPath), page2.name), pageStem + ".png", pageStem + ".ktx2", ...pages.length === 1 ? [stem + ".png", stem + ".ktx2"] : []], `atlas page image ${page2.name}`);
+    let pngPath = imagePath;
+    if (extname(imagePath).toLowerCase() === ".ktx2") {
+      pngPath = join8(rigDir, basename4(imagePath).replace(/\.ktx2$/i, ".png"));
+      if (!await exists(pngPath)) {
+        const { png } = await ktx2ToPng(new Uint8Array(await readFile7(imagePath)));
+        await writeFile5(pngPath, png);
+      }
     }
+    pagePaths.set(page2.name, pngPath);
   }
-  const pageImage = relative(rigDir, pngPath).split("\\").join("/");
+  const pageImage = (page2) => relative(rigDir, pagePaths.get(page2)).split("\\").join("/");
   const name = opts.name ?? basename4(stem);
-  return { ...importSpine(json, atlasText, { name, pageImage, margin: opts.margin, notes: opts.notes }), imagePath: pngPath };
+  const imagePaths = [...pagePaths.values()];
+  return { ...importSpine(json, atlasText, { name, skin: opts.skin, pageImage, margin: opts.margin, notes: opts.notes }), imagePath: imagePaths[0], imagePaths };
 }
 
 // src/rig-templates.ts
@@ -4609,7 +4890,7 @@ function extractTemplate(doc, animId, name, groups = {}) {
   const tracks = [];
   const skipped = [];
   for (const t of anim.tracks) {
-    if (t.target === "drawOrder" || t.keys.some((k) => Array.isArray(k.v))) {
+    if (t.target === "control" || t.target === "drawOrder" || t.keys.some((k) => Array.isArray(k.v))) {
       skipped.push(trackId5(t));
       continue;
     }
@@ -4984,8 +5265,8 @@ function runGates(doc, config) {
     let active2 = 0, bad = 0;
     for (const t of ts) {
       const pose = poseOf(animation, t), s = evaluate(doc, pose);
-      const color = pose.get(pk("slot", slot.id, "color")) ?? colorToArray(slot.color);
-      const alpha = Number(pose.get(pk("slot", slot.id, "alpha")) ?? slot.alpha) * color[3];
+      const color = s.pose.get(pk("slot", slot.id, "color")) ?? colorToArray(slot.color);
+      const alpha = Number(s.pose.get(pk("slot", slot.id, "alpha")) ?? slot.alpha) * color[3];
       if (!s.attachment.get(slot.id) || alpha <= 0.01) continue;
       active2++;
       const v = bone(s, rule.bone, rule.prop === "rotation" ? "rotation" : "position", rule.space)[rule.prop === "y" ? 1 : 0];
@@ -5125,13 +5406,14 @@ function attachToBone(doc, animation, bone, target, t) {
   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 handedness = to.a * to.d - to.b * to.c < 0 ? -1 : 1;
   const offset = {
     x,
     y,
-    rotation: wrap2(rotationOf(from) - rotationOf(to)),
+    rotation: wrap2(rotationOf(from) - rotationOf(to)) * handedness,
     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)
+    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) * handedness
   };
   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 });
@@ -5207,6 +5489,53 @@ function bakeSecondary(doc, animation, opts) {
   return next;
 }
 
+// src/rig-control-qa.ts
+function snapshot(doc, values2) {
+  const skel = evaluate(doc, controlPose(doc, values2));
+  return doc.slots.flatMap((slot) => {
+    const alpha = Number(skel.pose.get(`slot:${slot.id}:alpha`) ?? slot.alpha);
+    const points = slotOutline(doc, skel.pose, slot.id, 1, skel);
+    return points ? [{ id: slot.id, alpha, points }] : [];
+  });
+}
+function checkControlCases(doc, cases) {
+  const errors = [];
+  const rest = evaluate(doc, /* @__PURE__ */ new Map());
+  cases.forEach((c, index) => {
+    const skel = evaluate(doc, controlPose(doc, c.values));
+    for (const [id, b] of skel.bones) if (Object.values(b.world).some((v) => !Number.isFinite(v)))
+      errors.push({ case: index, subject: id, message: "non-finite bone transform" });
+    for (const att of doc.attachments) if (att.type === "mesh") {
+      const before = attachmentWorldVertices(rest, att.slot, att), after = attachmentWorldVertices(skel, att.slot, att);
+      if (after.some((v) => !Number.isFinite(v))) errors.push({ case: index, subject: att.id, message: "non-finite mesh vertices" });
+      else if (foldedTriangles(before, after, att.triangles).length || att.triangles.some((_, i) => i % 3 === 0 && Math.abs(triangleArea(before, ...att.triangles.slice(i, i + 3))) > 1e-8 && Math.abs(triangleArea(after, ...att.triangles.slice(i, i + 3))) < 1e-8))
+        errors.push({ case: index, subject: att.id, message: "mesh triangle reversed or collapsed" });
+    }
+  });
+  const neutral = JSON.stringify(snapshot(doc, {}));
+  const effects = (doc.controls ?? []).map((c) => ({
+    id: c.id,
+    geometryOrOpacityChanged: [c.min, c.max].some((v) => JSON.stringify(snapshot(doc, { [c.id]: v })) !== neutral)
+  }));
+  return {
+    passed: errors.length === 0,
+    errors,
+    effects,
+    scope: "Finite transforms and mesh orientation at the listed poses; individual control geometry/opacity effects. Images require visual review; this is not an artwork acceptance result."
+  };
+}
+function makeControlSweep(doc, probes) {
+  const cases = controlCases(doc, probes).map((c) => ({ ...c, values: { ...Object.fromEntries((doc.controls ?? []).map((p) => [p.id, p.default])), ...c.values } }));
+  const animation = {
+    id: "control_sweep",
+    duration: Math.max(1, cases.length - 1),
+    loop: false,
+    events: [],
+    tracks: (doc.controls ?? []).map((c) => ({ target: "control", id: c.id, prop: "value", keys: cases.map((p, i) => ({ t: i, v: p.values[c.id], ease: "step" })) }))
+  };
+  return { cases, doc: parse({ ...doc, animations: [animation] }), animation: animation.id, times: cases.map((_, i) => i) };
+}
+
 // src/rig-api.ts
 var tools = [];
 function tool(name, description, input, run) {
@@ -5270,14 +5599,88 @@ function previewCheck(doc, animation) {
   const a = animation ? doc.animations.find((x) => x.id === animation) : void 0;
   return a ? `check: OK for "${a.id}" (${a.tracks.length} tracks, ${a.duration}s${a.loop ? " loop" : ""})` : "check: OK (rest pose)";
 }
-var TrackRef = { interpolation: z3.enum(["segment", "pchip"]).optional().describe("pchip: smooth through numeric keys, preserving extrema; segment: per-key easing"), target: z3.enum(["bone", "slot", "deform", "ik", "transform", "path", "drawOrder"]), id: z3.string(), prop: z3.string() };
+var TrackRef = { interpolation: z3.enum(["segment", "pchip"]).optional().describe("pchip: smooth through numeric keys, preserving extrema; segment: per-key easing"), target: z3.enum(["bone", "slot", "deform", "ik", "transform", "path", "drawOrder", "control"]), id: z3.string(), prop: z3.string() };
+tool(
+  "rig_set_control",
+  "Create or replace a semantic control with a finite min/max/default range. Animate target=control, prop=value. Changing a range requires matching binding grids.",
+  { path: Path, control: RigControl },
+  async ({ path, control }) => mutate(path, (d) => ({ ...d, controls: [...(d.controls ?? []).filter((c) => c.id !== control.id), control] }))
+);
+tool(
+  "rig_set_control_binding",
+  "Create or replace a 1D/2D grid of absolute keyforms. First axis varies fastest. Channels support bone transforms, slot alpha and mesh/path vertex offsets. Each channel has one owner; animate controls rather than owned channels.",
+  { path: Path, binding: ControlBinding },
+  async ({ path, binding }) => mutate(path, (d) => ({ ...d, controlBindings: [...(d.controlBindings ?? []).filter((b) => b.id !== binding.id), binding] }))
+);
+tool(
+  "rig_remove_control_binding",
+  "Remove a control binding, restoring its channels to setup/animation values.",
+  { path: Path, id: z3.string() },
+  async ({ path, id }) => mutate(path, (d) => {
+    if (!d.controlBindings?.some((b) => b.id === id)) throw new Error(`unknown binding "${id}"`);
+    return { ...d, controlBindings: d.controlBindings.filter((b) => b.id !== id) };
+  })
+);
+tool(
+  "rig_remove_control",
+  "Remove an unused control and its animation tracks. Remove dependent bindings first.",
+  { path: Path, id: z3.string() },
+  async ({ path, id }) => mutate(path, (d) => {
+    if (!d.controls?.some((c) => c.id === id)) throw new Error(`unknown control "${id}"`);
+    if (d.controlBindings?.some((b) => b.axes.some((a) => a.control === id))) throw new Error("remove dependent control bindings first");
+    return { ...d, controls: d.controls.filter((c) => c.id !== id), animations: d.animations.map((a) => ({ ...a, tracks: a.tracks.filter((t) => t.target !== "control" || t.id !== id) })) };
+  })
+);
+tool(
+  "rig_sweep_controls",
+  "Render an explicit control grid (max 256 poses) through PixiJS, with PNGs, contact sheet and report tying cases to source/texture/renderer hashes. Geometry checks are not visual acceptance. Use a new output directory outside the packed rig.",
+  {
+    path: Path,
+    probes: z3.record(z3.array(z3.number().finite()).min(1)),
+    output: z3.string(),
+    scale: z3.number().positive().max(2).default(0.5),
+    region: z3.tuple([z3.number(), z3.number(), z3.number().positive(), z3.number().positive()]).optional()
+  },
+  async ({ path, probes, output, scale, region }) => {
+    try {
+      const raw = await readFile9(path, "utf8"), d = parse(JSON.parse(raw));
+      const sweep = makeControlSweep(d, probes), out = resolveFrom(path, output);
+      if (await exists2(out) && (await readdir4(out)).length) throw new Error("sweep output must be a new or empty directory");
+      const qa = checkControlCases(d, sweep.cases);
+      const r = await renderPreview(sweep.doc, { assetsDir: dirname8(path), animation: sweep.animation, times: sweep.times, scale, region, transparent: true });
+      await mkdir6(out, { recursive: true });
+      const frames = [];
+      for (let i = 0; i < r.frames.length; i++) {
+        const file = `pose-${String(i).padStart(3, "0")}.png`;
+        await writeFile7(join9(out, file), r.frames[i]);
+        frames.push({ file, sha256: sha256(r.frames[i]), ...sweep.cases[i] });
+      }
+      await writeFile7(join9(out, "sheet.png"), r.sheet);
+      const report = {
+        version: 1,
+        sourceRig: sha256(raw),
+        identity: r.identity,
+        scale,
+        region: region ?? null,
+        ...qa,
+        frames,
+        sheet: { file: "sheet.png", sha256: sha256(r.sheet) }
+      };
+      await saveJson(join9(out, "report.json"), report);
+      return { text: JSON.stringify({ output: out, poseCount: frames.length, ...qa }), image: r.sheet };
+    } catch (e) {
+      return fail(e);
+    }
+  }
+);
 var KeyIn = z3.object({
   t: z3.number().describe("seconds"),
   v: z3.union([z3.number(), z3.string(), z3.null(), z3.array(z3.number()), z3.array(z3.string())]),
+  componentEase: z3.array(Ease).min(1).optional().describe("optional independent easing per numeric-array component"),
   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].";
+var KEY_DOC = "Keys are {t, v, ease?, componentEase?}; componentEase selects independent easing for numeric-array components. 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.",
@@ -5401,19 +5804,20 @@ tool(
 );
 tool(
   "rig_import_spine",
-  "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.",
+  "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; named pages resolve beside the atlas, and KTX2 pages transcode to PNG next to rig.json. Read warnings for unsupported physics and dark tint. Then use rig_get / rig_render_preview / rig_check as with any rig.",
   {
     path: Path,
     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"),
+    skin: z3.string().optional().describe("skin to flatten; default: default skin, or first skin if no default exists; no runtime skin switching"),
     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 }) => {
+  async ({ path, json, atlas, image, name, skin: skin2, margin, notes }) => {
     try {
-      const r = await importSpineProject({ json: resolveFrom(path, json), atlas: atlas && resolveFrom(path, atlas), image: image && resolveFrom(path, image), rigPath: path, name, margin, notes });
+      const r = await importSpineProject({ json: resolveFrom(path, json), atlas: atlas && resolveFrom(path, atlas), image: image && resolveFrom(path, image), rigPath: path, name, skin: skin2, margin, notes });
       const res = await create(path, parse(r.doc));
       if (r.warnings.length) res.text += `
 warnings:
@@ -6102,8 +6506,8 @@ tool(
       const r = await renderPreview(doc, { assetsDir: dirname8(path), ...opts });
       if (saveTo) await writeFile7(saveTo, r.sheet);
       if (framesDir) {
-        const { mkdir: mkdir6 } = await import("node:fs/promises");
-        await mkdir6(framesDir, { recursive: true });
+        const { mkdir: mkdir7 } = await import("node:fs/promises");
+        await mkdir7(framesDir, { recursive: true });
         const frames = r.frames.map((frame, i) => ({ file: `${String(i).padStart(6, "0")}.png`, sha256: sha256(frame) }));
         for (let i = 0; i < frames.length; i++) await writeFile7(join9(framesDir, frames[i].file), r.frames[i]);
         const manifest = {