@energy8platform/golem 0.5.0 → 0.6.0

package/dist/lib/spine-import.d.ts

@@ -26,6 +26,8 @@ export declare function parseAtlas(text: string): {
 };
 export interface ImportOptions {
     name?: string;
+    /** Flatten this skin into setup/attachment timelines, falling back only to the default skin. */
+    skin?: string;
     /** file name to use for the atlas page image(s) in asset.src (e.g. "ross.png" after transcoding a ktx2) */
     pageImage?: string | ((page: string) => string);
     /** canvas margin around the skeleton bounds, px */
@@ -58,11 +60,13 @@ export interface SpineProjectOptions {
     /** where the rig will live: the page asset is referenced relative to its directory (KTX2 pages are written there as PNG) */
     rigPath: string;
     name?: string;
+    skin?: string;
     margin?: number;
     notes?: string;
 }
 /** Import a Spine project from files. Resolves the atlas and page image, transcodes KTX2 pages to PNG next to the rig. */
 export declare function importSpineProject(opts: SpineProjectOptions): Promise<ReturnType<typeof importSpine> & {
     imagePath: string;
+    imagePaths: string[];
 }>;
 export {};

package/dist/lib/tools.js

@@ -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,7 +287,9 @@ 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", [
@@ -472,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;
@@ -555,6 +563,7 @@ function validate(doc) {
       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") {
@@ -732,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;
 }
@@ -825,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();
@@ -857,11 +873,11 @@ 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);
@@ -1104,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) {
@@ -1266,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;
@@ -1300,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 };
@@ -1332,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) {
@@ -1361,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": {
@@ -1389,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"));
@@ -2148,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));
 }
@@ -2544,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) }))
       };
     }
@@ -4157,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;
@@ -4165,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;
@@ -4172,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}`;
@@ -4196,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)) {
@@ -4211,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";
@@ -4219,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]));
@@ -4249,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) {
@@ -4269,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 ?? {})) {
@@ -4280,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;
@@ -4303,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,
@@ -4319,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)),
@@ -4346,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)),
@@ -4366,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)),
@@ -4401,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;
   };
@@ -4412,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) {
@@ -4452,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`);
@@ -4503,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);
@@ -4534,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));
     }
@@ -4555,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));
@@ -4717,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
@@ -5264,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 });
@@ -5533,10 +5676,11 @@ tool(
 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.",
@@ -5660,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: