@energy8platform/golem 0.2.0 → 0.3.0

package/dist/lib/harness.js

@@ -49413,7 +49413,7 @@ ${parts.join("\n")}
   var ID_RE = /^[a-z][a-z0-9_]*$/;
   var Id = external_exports.string().regex(ID_RE, "snake_case id");
   var Ease = external_exports.union([
-    external_exports.enum(["linear", "step", "ease_in", "ease_out", "ease_in_out", "back_out", "elastic_out"]),
+    external_exports.enum(["linear", "step", "ease_in", "ease_out", "ease_in_out", "minimum_jerk", "back_out", "elastic_out"]),
     // cubic-bezier control points, same semantics as CSS
     external_exports.object({ bezier: external_exports.tuple([external_exports.number(), external_exports.number(), external_exports.number(), external_exports.number()]) })
   ]);
@@ -49445,6 +49445,7 @@ ${parts.join("\n")}
     /** where this layer came from — provenance for agents */
     origin: external_exports.object({
       sourceImage: external_exports.string().optional(),
+      bboxSpace: external_exports.enum(["source", "document"]).optional(),
       /** bbox in source image: [x, y, w, h] */
       bbox: external_exports.tuple([external_exports.number(), external_exports.number(), external_exports.number(), external_exports.number()]).optional(),
       inpainted: external_exports.boolean().default(false),
@@ -49467,6 +49468,8 @@ ${parts.join("\n")}
   var Slot = external_exports.object({
     id: Id,
     bone: Id,
+    /** Closed path attachment used as a moving clipping mask. */
+    clip: Id.optional(),
     /** active attachment id; undefined = hidden */
     attachment: Id.optional(),
     alpha: external_exports.number().min(0).max(1).default(1),
@@ -49529,6 +49532,8 @@ ${parts.join("\n")}
     order: external_exports.number().int().default(0),
     bones: external_exports.array(Id).min(1),
     target: Id,
+    iterations: external_exports.number().int().min(1).max(1e3).optional(),
+    tolerance: external_exports.number().positive().optional(),
     mix: external_exports.number().default(1),
     softness: external_exports.number().default(0),
     bendPositive: external_exports.boolean().default(true),
@@ -49576,7 +49581,7 @@ ${parts.join("\n")}
   var SlotProp = external_exports.enum(["alpha", "attachment", "z", "color"]);
   var DeformProp = external_exports.string().regex(/^(bulge|bend|sway|squash|p[0-2][0-2][xy]|vertices)$/, "deform prop must be bulge|bend|sway|squash|p<row><col>x|y|vertices");
   var IkProp = external_exports.enum(["mix", "softness", "bendPositive", "compress", "stretch"]);
-  var TransformProp = external_exports.enum(["mixRotate", "mixX", "mixY", "mixScaleX", "mixScaleY", "mixShearY"]);
+  var TransformProp = external_exports.enum(["mixRotate", "mixX", "mixY", "mixScaleX", "mixScaleY", "mixShearY", "x", "y", "rotation", "scaleX", "scaleY", "shearY"]);
   var PathProp = external_exports.enum(["position", "spacing", "mixRotate", "mixX", "mixY"]);
   var KeyValue = external_exports.union([external_exports.number(), external_exports.string(), external_exports.null(), external_exports.array(external_exports.number()), external_exports.array(external_exports.string())]);
   var Key = external_exports.object({
@@ -49585,14 +49590,15 @@ ${parts.join("\n")}
     /** easing INTO the next key */
     ease: Ease.default("ease_in_out")
   });
+  var Interpolation = { interpolation: external_exports.enum(["segment", "pchip"]).optional() };
   var Track = external_exports.discriminatedUnion("target", [
-    external_exports.object({ target: external_exports.literal("bone"), id: Id, prop: BoneProp, keys: external_exports.array(Key).min(1) }),
-    external_exports.object({ target: external_exports.literal("slot"), id: Id, prop: SlotProp, keys: external_exports.array(Key).min(1) }),
-    external_exports.object({ target: external_exports.literal("deform"), id: Id, prop: DeformProp, keys: external_exports.array(Key).min(1) }),
-    external_exports.object({ target: external_exports.literal("ik"), id: Id, prop: IkProp, keys: external_exports.array(Key).min(1) }),
-    external_exports.object({ target: external_exports.literal("transform"), id: Id, prop: TransformProp, keys: external_exports.array(Key).min(1) }),
-    external_exports.object({ target: external_exports.literal("path"), id: Id, prop: PathProp, keys: external_exports.array(Key).min(1) }),
-    external_exports.object({ target: external_exports.literal("drawOrder"), id: Id.default("order"), prop: external_exports.literal("order").default("order"), keys: external_exports.array(Key).min(1) })
+    external_exports.object({ target: external_exports.literal("bone"), id: Id, prop: BoneProp, ...Interpolation, keys: external_exports.array(Key).min(1) }),
+    external_exports.object({ target: external_exports.literal("slot"), id: Id, prop: SlotProp, ...Interpolation, keys: external_exports.array(Key).min(1) }),
+    external_exports.object({ target: external_exports.literal("deform"), id: Id, prop: DeformProp, ...Interpolation, keys: external_exports.array(Key).min(1) }),
+    external_exports.object({ target: external_exports.literal("ik"), id: Id, prop: IkProp, ...Interpolation, keys: external_exports.array(Key).min(1) }),
+    external_exports.object({ target: external_exports.literal("transform"), id: Id, prop: TransformProp, ...Interpolation, keys: external_exports.array(Key).min(1) }),
+    external_exports.object({ target: external_exports.literal("path"), id: Id, prop: PathProp, ...Interpolation, keys: external_exports.array(Key).min(1) }),
+    external_exports.object({ target: external_exports.literal("drawOrder"), id: Id.default("order"), prop: external_exports.literal("order").default("order"), ...Interpolation, keys: external_exports.array(Key).min(1) })
   ]);
   var Event2 = external_exports.object({
     t: external_exports.number().nonnegative(),
@@ -49734,6 +49740,10 @@ ${parts.join("\n")}
       if (a2.frame && !a2.trim && !a2.rotate && (a2.frame[2] !== a2.width || a2.frame[3] !== a2.height)) errs.push(`asset "${a2.id}": frame size must equal width\xD7height (or declare trim/rotate)`);
     }
     for (const s2 of doc.slots) {
+      if (s2.clip) {
+        const mask = attachments.get(s2.clip);
+        if (mask?.type !== "path" || !mask.closed) errs.push(`slot "${s2.id}": clip must name a closed path attachment`);
+      }
       if (!bones.has(s2.bone)) errs.push(`slot "${s2.id}": unknown bone "${s2.bone}"`);
       if (s2.attachment) {
         const a2 = attachments.get(s2.attachment);
@@ -49765,7 +49775,8 @@ ${parts.join("\n")}
       }
     }
     for (const c2 of doc.ik) {
-      if (c2.bones.length > 2) errs.push(`ik "${c2.id}": must have 1 or 2 bones`);
+      for (let i2 = 1; i2 < c2.bones.length; i2++) if (doc.bones.find((b2) => b2.id === c2.bones[i2])?.parent !== c2.bones[i2 - 1])
+        errs.push(`ik "${c2.id}": bones must form a contiguous parent-to-child chain`);
       for (const b2 of c2.bones) if (!bones.has(b2)) errs.push(`ik "${c2.id}": unknown bone "${b2}"`);
       if (!bones.has(c2.target)) errs.push(`ik "${c2.id}": unknown target bone "${c2.target}"`);
     }
@@ -49837,6 +49848,7 @@ ${parts.join("\n")}
     ease_in: (t2) => t2 * t2,
     ease_out: (t2) => 1 - (1 - t2) * (1 - t2),
     ease_in_out: (t2) => t2 < 0.5 ? 2 * t2 * t2 : 1 - (-2 * t2 + 2) ** 2 / 2,
+    minimum_jerk: (t2) => t2 * t2 * t2 * (10 + t2 * (-15 + 6 * t2)),
     back_out: (t2) => 1 + 2.70158 * (t2 - 1) ** 3 + 1.70158 * (t2 - 1) ** 2,
     elastic_out: (t2) => t2 === 0 ? 0 : t2 === 1 ? 1 : 2 ** (-10 * t2) * Math.sin((t2 * 10 - 0.75) * (2 * Math.PI / 3)) + 1
   };
@@ -49868,7 +49880,25 @@ ${parts.join("\n")}
     return f2;
   }
   var pk = (target, id, prop) => `${target}:${id}:${prop}`;
-  function sample(track, t2) {
+  function smoothValue(track, i2, t2, component, loop) {
+    const k2 = track.keys, n2 = k2.length;
+    const v2 = (j2) => component === void 0 ? k2[j2].v : k2[j2].v[component];
+    const h2 = (j2) => k2[j2 + 1].t - k2[j2].t;
+    const d2 = (j2) => (v2(j2 + 1) - v2(j2)) / h2(j2);
+    const harmonic = (a2, b2, h0, h1) => a2 * b2 <= 0 ? 0 : 3 * (h0 + h1) / ((2 * h1 + h0) / a2 + (h1 + 2 * h0) / b2);
+    const tangent = (j2) => {
+      if (j2 === 0 || j2 === n2 - 1) {
+        if (loop && n2 > 2 && v2(0) === v2(n2 - 1) && k2[0].ease !== "step" && k2[n2 - 2].ease !== "step")
+          return harmonic(d2(n2 - 2), d2(0), h2(n2 - 2), h2(0));
+        return 0;
+      }
+      if (k2[j2 - 1].ease === "step" || k2[j2].ease === "step") return 0;
+      return harmonic(d2(j2 - 1), d2(j2), h2(j2 - 1), h2(j2));
+    };
+    const u2 = (t2 - k2[i2].t) / h2(i2), u22 = u2 * u2, u3 = u22 * u2;
+    return (2 * u3 - 3 * u22 + 1) * v2(i2) + (u3 - 2 * u22 + u2) * h2(i2) * tangent(i2) + (-2 * u3 + 3 * u22) * v2(i2 + 1) + (u3 - u22) * h2(i2) * tangent(i2 + 1);
+  }
+  function sample(track, t2, loop = false) {
     const keys = track.keys;
     if (t2 <= keys[0].t) return keys[0].v;
     const last = keys[keys.length - 1];
@@ -49876,31 +49906,38 @@ ${parts.join("\n")}
     let i2 = 0;
     while (keys[i2 + 1].t <= t2) i2++;
     const a2 = keys[i2], b2 = keys[i2 + 1];
+    if (a2.ease === "step") return a2.v;
     if (typeof a2.v === "number" && typeof b2.v === "number") {
+      if (track.interpolation === "pchip") return smoothValue(track, i2, t2, void 0, loop);
       const u2 = ease(a2.ease)((t2 - a2.t) / (b2.t - a2.t));
       return a2.v + (b2.v - a2.v) * u2;
     }
     if (Array.isArray(a2.v) && Array.isArray(b2.v) && typeof a2.v[0] === "number") {
+      if (track.interpolation === "pchip") return a2.v.map((_, j2) => smoothValue(track, i2, t2, j2, loop));
       const u2 = ease(a2.ease)((t2 - a2.t) / (b2.t - a2.t)), av = a2.v, bv = b2.v;
       return av.map((v2, k2) => v2 + ((bv[k2] ?? v2) - v2) * u2);
     }
     return a2.v;
   }
   function poseOf(anim, t2, out2 = /* @__PURE__ */ new Map()) {
-    for (const tr of anim.tracks) out2.set(pk(tr.target, tr.id, tr.prop), sample(tr, t2));
+    for (const tr of anim.tracks) out2.set(pk(tr.target, tr.id, tr.prop), sample(tr, t2, anim.loop && tr.keys[0].t === 0 && tr.keys.at(-1).t === anim.duration));
     return out2;
   }
   function blendPoses(from, to, w2, restOf) {
-    const out2 = new Map(to);
-    for (const [k2, f2] of from) {
-      const cur = to.get(k2);
-      if (typeof f2 === "number") {
+    if (w2 >= 1) return new Map(to);
+    const out2 = /* @__PURE__ */ new Map();
+    for (const k2 of /* @__PURE__ */ new Set([...from.keys(), ...to.keys()])) {
+      const f2 = from.has(k2) ? from.get(k2) : restOf(k2);
+      const cur = to.has(k2) ? to.get(k2) : restOf(k2);
+      if (typeof f2 === "number" && !Array.isArray(cur)) {
         const target = typeof cur === "number" ? cur : restOf(k2);
         out2.set(k2, f2 + (target - f2) * w2);
       } else if (Array.isArray(f2) && typeof f2[0] === "number") {
         const fv = f2, tv = Array.isArray(cur) && typeof cur[0] === "number" ? cur : fv.map(() => 0);
         out2.set(k2, fv.map((v2, i2) => v2 + ((tv[i2] ?? 0) - v2) * w2));
-      } else if (cur === void 0 && w2 < 1) out2.set(k2, f2);
+      } else if (Array.isArray(cur) && typeof cur[0] === "number" && typeof f2 !== "string") {
+        out2.set(k2, cur.map((v2) => v2 * w2));
+      } else out2.set(k2, f2 ?? null);
     }
     return out2;
   }
@@ -50069,10 +50106,43 @@ ${parts.join("\n")}
     updateSubtree(skel, boneId);
   }
   var shortest = (deg) => ((deg + 180) % 360 + 360) % 360 - 180;
+  function applyLongIk(skel, c2, tx, ty, mix) {
+    const initial = c2.bones.map((id) => ({ ...skel.bones.get(id) }));
+    const last = c2.bones.at(-1), len = boneOf(skel.doc, last).length;
+    const end = () => apply(skel.bones.get(last).world, len, 0);
+    const tolerance = c2.tolerance ?? 0.05;
+    const root = skel.bones.get(c2.bones[0]).world, tip = end();
+    if (Math.abs((tip[0] - root.tx) * (ty - root.ty) - (tip[1] - root.ty) * (tx - root.tx)) < 1e-7 && Math.hypot(tx - root.tx, ty - root.ty) < Math.hypot(tip[0] - root.tx, tip[1] - root.ty) - tolerance) {
+      skel.bones.get(last).rotation += cnum(skel, "ik", c2.id, "bendPositive", c2.bendPositive) > 0.5 ? 5 : -5;
+      updateSubtree(skel, last);
+    }
+    for (let iter = 0; iter < (c2.iterations ?? 100); iter++) {
+      const e2 = end();
+      if (Math.hypot(e2[0] - tx, e2[1] - ty) <= tolerance) break;
+      for (let i2 = c2.bones.length - 1; i2 >= 0; i2--) {
+        const id = c2.bones[i2], b2 = boneOf(skel.doc, id), st = skel.bones.get(id), w2 = st.world, e3 = end();
+        const angle = wrapRad(Math.atan2(ty - w2.ty, tx - w2.tx) - Math.atan2(e3[1] - w2.ty, e3[0] - w2.tx));
+        const cos = Math.cos(angle), sin = Math.sin(angle);
+        setEffectiveWorld(skel, b2, st, { ...w2, a: cos * w2.a - sin * w2.b, b: sin * w2.a + cos * w2.b, c: cos * w2.c - sin * w2.d, d: sin * w2.c + cos * w2.d });
+      }
+    }
+    if (mix < 1) {
+      c2.bones.forEach((id, i2) => {
+        const st = skel.bones.get(id), from = initial[i2];
+        for (const p2 of ["rotation", "shearX", "shearY"]) st[p2] = from[p2] + shortest(st[p2] - from[p2]) * mix;
+        for (const p2 of ["x", "y", "scaleX", "scaleY"]) st[p2] = from[p2] + (st[p2] - from[p2]) * mix;
+      });
+      updateSubtree(skel, c2.bones[0]);
+    }
+  }
   function applyIk(skel, c2) {
     const mix = cnum(skel, "ik", c2.id, "mix", c2.mix);
     if (mix <= 0) return;
     const target = skel.bones.get(c2.target).world;
+    if (c2.bones.length > 2) {
+      applyLongIk(skel, c2, target.tx, target.ty, mix);
+      return;
+    }
     const bendDir = cnum(skel, "ik", c2.id, "bendPositive", c2.bendPositive) > 0.5 ? 1 : -1;
     const compress = cnum(skel, "ik", c2.id, "compress", c2.compress) > 0.5, stretch = cnum(skel, "ik", c2.id, "stretch", c2.stretch) > 0.5;
     let softness = cnum(skel, "ik", c2.id, "softness", c2.softness);
@@ -50207,6 +50277,7 @@ ${parts.join("\n")}
     const mixRotate = cnum(skel, "transform", c2.id, "mixRotate", c2.mixRotate), mixX = cnum(skel, "transform", c2.id, "mixX", c2.mixX), mixY = cnum(skel, "transform", c2.id, "mixY", c2.mixY);
     const mixScaleX = cnum(skel, "transform", c2.id, "mixScaleX", c2.mixScaleX), mixScaleY = cnum(skel, "transform", c2.id, "mixScaleY", c2.mixScaleY), mixShearY = cnum(skel, "transform", c2.id, "mixShearY", c2.mixShearY);
     if (!mixRotate && !mixX && !mixY && !mixScaleX && !mixScaleY && !mixShearY) return;
+    c2 = { ...c2, ...Object.fromEntries(["x", "y", "rotation", "scaleX", "scaleY", "shearY"].map((p2) => [p2, cnum(skel, "transform", c2.id, p2, c2[p2])])) };
     const target = skel.bones.get(c2.target), tw = target.world;
     const offsetRotation = c2.rotation * DEG2, offsetShearY = c2.shearY * DEG2;
     for (const id of c2.bones) {
@@ -50534,6 +50605,7 @@ ${parts.join("\n")}
   var AnimationState = class {
     constructor(sink, opts = {}) {
       this.sink = sink;
+      this.opts = opts;
       this.defaultMix = opts.mix ?? 0;
     }
     onEvent;
@@ -50558,11 +50630,18 @@ ${parts.join("\n")}
     }
     channel(id, loop, priority = 0) {
       const anim = this.sink.doc.animations.find((a2) => a2.id === id);
-      if (!anim) throw new Error(`unknown animation "${id}"`);
+      if (!anim) {
+        const message = `unknown animation "${id}"; available: ${this.sink.doc.animations.map((a2) => a2.id).join(", ")}`;
+        if (this.opts.missingAnimation === "throw") throw new Error(message);
+        (this.opts.onWarning ?? console.warn)(message);
+        return void 0;
+      }
       return { anim, time: 0, loop: loop ?? anim.loop, done: false, priority, fresh: true };
     }
     setBase(id, opts = {}) {
-      this.base = id === void 0 ? void 0 : this.channel(id);
+      const next = id === void 0 ? void 0 : this.channel(id);
+      if (id !== void 0 && !next) return;
+      this.base = next;
       if (!this.main || this.main.done) {
         this.main = void 0;
         this.beginMix(opts.mix);
@@ -50571,6 +50650,16 @@ ${parts.join("\n")}
     }
     play(id, opts = {}) {
       const ch = this.channel(id, opts.loop, opts.priority ?? 0);
+      if (!ch) {
+        this.main?.settle?.("interrupted");
+        for (const queued of this.queue) queued.settle?.("dropped");
+        this.main = void 0;
+        this.queue = [];
+        this.beginMix(opts.mix);
+        this.update(0);
+        opts.onComplete?.("dropped");
+        return Promise.resolve("dropped");
+      }
       const promise2 = new Promise((resolve) => {
         ch.settle = (r2) => {
           ch.settle = void 0;
@@ -50591,7 +50680,10 @@ ${parts.join("\n")}
     /** Independent loop on top of the shown pose; `undefined` removes it. */
     setOverlay(name, id) {
       if (id === void 0) this.overlays.delete(name);
-      else this.overlays.set(name, this.channel(id));
+      else {
+        const ch = this.channel(id);
+        if (ch) this.overlays.set(name, ch);
+      }
     }
     /** Clear everything and show the setup pose. Pending plays resolve as "stopped". */
     stop() {
@@ -50676,6 +50768,7 @@ ${parts.join("\n")}
   // src/rig-runtime.ts
   var DEG3 = Math.PI / 180;
   var MESH_GRID = 9;
+  var GHOST_ALPHA = 0.5;
   async function createTextures(doc, loadSource) {
     const bySrc = /* @__PURE__ */ new Map(), out2 = /* @__PURE__ */ new Map();
     for (const a2 of doc.assets) {
@@ -50715,7 +50808,7 @@ ${parts.join("\n")}
   var rgbOf = (c2) => Math.round(c2[0] * 255) << 16 | Math.round(c2[1] * 255) << 8 | Math.round(c2[2] * 255);
   var sameNumbers = (a2, b2) => a2 === b2 || a2.length === b2.length && a2.every((v2, i2) => v2 === b2[i2]);
   var RigPlayer = class {
-    /** `mix`: default crossfade seconds for state transitions (setBase, completion → base); play() passes its own */
+    /** Default crossfade is 0.18 seconds; explicit mix: 0 requests a hard cut. */
     constructor(doc, textures, opts = {}) {
       this.doc = doc;
       parse2(doc);
@@ -50754,7 +50847,7 @@ ${parts.join("\n")}
         this.items.push(item);
         this.view.addChild(item.node);
       }
-      this.state = new AnimationState(this, { mix: opts.mix ?? 0 });
+      this.state = new AnimationState(this, { ...opts, mix: opts.mix ?? 0.18 });
       this.setPose(/* @__PURE__ */ new Map());
     }
     view = new Container();
@@ -50765,6 +50858,9 @@ ${parts.join("\n")}
     pages = /* @__PURE__ */ new Map();
     /** slots the editor hides; honoured by setPose */
     hidden = /* @__PURE__ */ new Set();
+    /** slots the editor has selected; setPose draws them at GHOST_ALPHA at least */
+    ghosts = /* @__PURE__ */ new Set();
+    clipGraphics = /* @__PURE__ */ new Map();
     /** whole atlas page as a plain texture (identity uv mapping) for skinned meshes */
     pageTexture(tex) {
       let page = this.pages.get(tex.source);
@@ -50776,7 +50872,7 @@ ${parts.join("\n")}
       this.state.onEvent = opts.onEvent;
       return this.state.play(animId, {
         loop: opts.loop,
-        mix: opts.mix ?? 0,
+        mix: opts.mix,
         ifBusy: "interrupt",
         onComplete: (r2) => {
           if (r2 === "completed") opts.onComplete?.();
@@ -50805,6 +50901,10 @@ ${parts.join("\n")}
       if (visible) this.hidden.delete(slotId);
       else this.hidden.add(slotId);
     }
+    /** Editor-only: draw these slots at GHOST_ALPHA at least, whatever the pose says (an empty list clears it). */
+    setGhostSlots(slotIds) {
+      this.ghosts = new Set(slotIds);
+    }
     /** Stop playback and immediately restore the complete setup pose. */
     stop() {
       this.state.stop();
@@ -50816,12 +50916,32 @@ ${parts.join("\n")}
     /** Apply a pose (rest where silent) to the display objects. */
     setPose(pose) {
       const skel = this.skel = evaluate(this.doc, pose);
+      const clips = new Set(this.doc.slots.flatMap((s2) => s2.clip ? [s2.clip] : []));
+      for (const [id, g2] of this.clipGraphics) if (!clips.has(id)) {
+        g2.destroy();
+        this.clipGraphics.delete(id);
+      }
+      for (const id of clips) {
+        const att = this.doc.attachments.find((a2) => a2.id === id);
+        if (att?.type !== "path" || !att.closed) continue;
+        let g2 = this.clipGraphics.get(id);
+        if (!g2) {
+          g2 = new Graphics();
+          this.clipGraphics.set(id, g2);
+          this.view.addChild(g2);
+        }
+        const vertices = attachmentWorldVertices(skel, att.slot, att);
+        const n2 = Math.max(32, vertices.length * 4);
+        const points = samplePath(vertices, true, att.lengths, true, Array.from({ length: n2 }, (_, i2) => i2 / n2), true);
+        g2.clear().poly(points.flatMap((p2) => [p2.x, p2.y]), true).fill(16777215);
+      }
       const m2 = new Matrix();
       const orderV = pose.get(pk("drawOrder", "order", "order"));
       const order = /* @__PURE__ */ new Map();
       if (Array.isArray(orderV)) orderV.forEach((id, i2) => order.set(id, i2));
       for (const it of this.items) {
         const s2 = it.slot, shown = skel.attachment.get(s2.id);
+        it.node.mask = s2.clip ? this.clipGraphics.get(s2.clip) ?? null : null;
         if (shown !== it.att || this.hidden.has(s2.id)) {
           it.node.visible = false;
           continue;
@@ -50829,7 +50949,8 @@ ${parts.join("\n")}
         it.node.visible = true;
         const colorV = pose.get(pk("slot", s2.id, "color"));
         const color = Array.isArray(colorV) && typeof colorV[0] === "number" ? colorV : colorToArray(s2.color);
-        it.node.alpha = numOf(pose, pk("slot", s2.id, "alpha"), s2.alpha) * color[3];
+        const alpha = numOf(pose, pk("slot", s2.id, "alpha"), s2.alpha) * color[3];
+        it.node.alpha = this.ghosts.has(s2.id) ? Math.max(alpha, GHOST_ALPHA) : alpha;
         it.node.tint = rgbOf(color);
         it.node.zIndex = order.size ? order.get(s2.id) ?? 0 : numOf(pose, pk("slot", s2.id, "z"), s2.z);
         if (it.skinned) {
@@ -50912,7 +51033,7 @@ ${parts.join("\n")}
       if (!assets[src]) throw new Error(`missing asset data for "${src}"`);
       return textureFromDataUrl(assets[src]);
     });
-    player = new RigPlayer(doc, textures);
+    player = new RigPlayer(doc, textures, { mix: 0 });
     player.view.scale.set(scale);
     overlay = new Container();
     overlay.scale.set(scale);
@@ -50957,7 +51078,7 @@ ${parts.join("\n")}
     };
     for (const t2 of opts.times) {
       if (opts.animation) {
-        player.play(opts.animation);
+        player.play(opts.animation, { mix: 0 });
         player.tick(t2);
       } else {
         player.stop();
@@ -50965,7 +51086,21 @@ ${parts.join("\n")}
       }
       if (opts.overlayBones) drawBones();
       else clearOverlay();
-      const frame = grab(1);
+      if (opts.weightBone) {
+        if (!player.doc.bones.some((b2) => b2.id === opts.weightBone)) throw new Error(`unknown weight bone "${opts.weightBone}"`);
+        const anim = player.doc.animations.find((a2) => a2.id === opts.animation), pose = anim ? poseOf(anim, anim.loop ? t2 % anim.duration : t2) : /* @__PURE__ */ new Map();
+        const skel = evaluate(player.doc, pose), g2 = new Graphics();
+        for (const att of skel.attachment.values()) if (att?.type === "mesh" && att.weights) {
+          const v2 = attachmentWorldVertices(skel, att.slot, att);
+          for (let j2 = 0; j2 < att.triangles.length; j2 += 3) {
+            const ids = att.triangles.slice(j2, j2 + 3);
+            const weight = ids.reduce((sum, i2) => sum + att.weights[i2].filter((w3) => w3.bone === opts.weightBone).reduce((s2, w3) => s2 + w3.w, 0), 0) / 3;
+            g2.poly(ids.flatMap((i2) => [v2[i2 * 2], v2[i2 * 2 + 1]]), true).fill({ color: Math.round(255 * weight) << 16 | Math.round(255 * (1 - weight)), alpha: 0.75 });
+          }
+        }
+        overlay.addChild(g2);
+      }
+      const frame = grab(opts.transparent ? 0 : 1);
       const ctx = frame.getContext("2d");
       if (opts.onionSkin && prev) {
         ctx.globalAlpha = 0.35;

package/dist/lib/preview/export-video.d.ts

@@ -0,0 +1,12 @@
+import type { RigDocument } from '../rig-format';
+import { type PreviewOptions } from './render-preview';
+/** Encode deterministic runtime frames at the requested rate; replace output only after a successful encode. */
+export declare function exportVideo(doc: RigDocument, opts: PreviewOptions & {
+    animation: string;
+    outFile: string;
+    fps?: number;
+}): Promise<{
+    frames: number;
+    fps: number;
+    duration: number;
+}>;

package/dist/lib/preview/harness.d.ts

@@ -3,6 +3,8 @@ export interface RenderOptions {
     times: number[];
     overlayBones?: boolean;
     background?: string;
+    transparent?: boolean;
+    weightBone?: string;
     scale?: number;
     sheetColumns?: number;
     onionSkin?: boolean;

package/dist/lib/preview/render-preview.d.ts

@@ -1,4 +1,5 @@
 import { type RigDocument } from "../rig-format";
+import { type CaptureIdentity } from "../rig-qa";
 export interface PreviewOptions {
     /** directory that asset.src paths are relative to */
     assetsDir: string;
@@ -9,6 +10,10 @@ export interface PreviewOptions {
     count?: number;
     overlayBones?: boolean;
     background?: string;
+    transparent?: boolean;
+    weightBone?: string;
+    /** Source image path -> grayscale mask PNG path, resolved relative to assetsDir. */
+    debugFillMasks?: Record<string, string>;
     scale?: number;
     sheetColumns?: number;
     /** ghost the previous frame under each frame */
@@ -17,6 +22,7 @@ export interface PreviewOptions {
     region?: [number, number, number, number];
 }
 export interface PreviewResult {
+    identity: CaptureIdentity;
     frames: Buffer[];
     sheet: Buffer;
     times: number[];

package/dist/lib/rig-anim.d.ts

@@ -13,7 +13,7 @@ export type Val = number | string | null | number[] | string[];
 /** key: "bone:id:prop" | "slot:id:prop" | "deform:id:prop" | "ik:id:prop" | "transform:id:prop" | "path:id:prop" | "drawOrder:order:order" */
 export type Pose = Map<string, Val>;
 export declare const pk: (target: string, id: string, prop: string) => string;
-export declare function sample(track: Track, t: number): Val;
+export declare function sample(track: Track, t: number, loop?: boolean): Val;
 export declare function poseOf(anim: Animation, t: number, out?: Pose): Pose;
 /** Crossfade: numbers (and number arrays) interpolate toward `to` (or rest when absent there); discrete values hold until w = 1. */
 export declare function blendPoses(from: Pose, to: Pose, w: number, restOf: (key: string) => Val): Pose;

package/dist/lib/rig-check.d.ts

@@ -17,6 +17,7 @@
  * path attachment — an error).
  */
 import { type RigDocument } from "./rig-format";
+import { type QualityOptions } from "./rig-quality";
 export interface Finding {
     level: "error" | "warn" | "info";
     code: string;
@@ -26,7 +27,7 @@ export interface Finding {
     animation?: string;
     time?: number;
 }
-export interface CheckOptions {
+export interface CheckOptions extends QualityOptions {
     /** only this animation (plus the rest pose) */
     animation?: string;
     /** sampling rate for outlines (default 30) and for the fold check (default 60) */

package/dist/lib/rig-constraints.d.ts

@@ -57,3 +57,66 @@ export declare function pathFromPoints(skel: Skeleton, slotId: string, points: P
     closed: boolean;
     lengths: number[];
 };
+/** Solver-order dependencies, including ancestors and skinned path control points. */
+export declare function constraintDependencies(doc: RigDocument): {
+    all: ({
+        id: string;
+        order: number;
+        bones: string[];
+        target: string;
+        mix: number;
+        softness: number;
+        bendPositive: boolean;
+        compress: boolean;
+        stretch: boolean;
+        uniform: boolean;
+        iterations?: number | undefined;
+        tolerance?: number | undefined;
+        kind: "ik";
+    } | {
+        x: number;
+        y: number;
+        rotation: number;
+        scaleX: number;
+        scaleY: number;
+        shearY: number;
+        id: string;
+        order: number;
+        bones: string[];
+        target: string;
+        local: boolean;
+        relative: boolean;
+        mixRotate: number;
+        mixX: number;
+        mixY: number;
+        mixScaleX: number;
+        mixScaleY: number;
+        mixShearY: number;
+        kind: "transform";
+    } | {
+        rotation: number;
+        id: string;
+        order: number;
+        bones: string[];
+        target: string;
+        mixRotate: number;
+        mixX: number;
+        mixY: number;
+        positionMode: "fixed" | "percent";
+        spacingMode: "length" | "fixed" | "percent" | "proportional";
+        rotateMode: "tangent" | "chain" | "chainScale";
+        position: number;
+        spacing: number;
+        kind: "path";
+    })[];
+    edges: {
+        reader: string;
+        readerKind: "path" | "transform" | "ik";
+        writer: string;
+        writerKind: "path" | "transform" | "ik";
+        bone: string;
+        late: boolean;
+    }[];
+};
+/** Stable topological order; cyclic dependencies require an authoring decision. */
+export declare function orderConstraints(doc: RigDocument): RigDocument;