@energy8platform/golem 0.2.1 → 0.5.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,16 @@ ${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("control"), id: Id, prop: external_exports.literal("value"), ...Interpolation, 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(),
@@ -49608,6 +49615,25 @@ ${parts.join("\n")}
     /** if generated from a preset — keep params so the agent can re-tune instead of re-keying */
     preset: external_exports.object({ name: external_exports.string(), params: external_exports.record(external_exports.unknown()) }).optional()
   });
+  var RigControl = external_exports.object({
+    id: Id,
+    label: external_exports.string().optional(),
+    min: external_exports.number().finite(),
+    max: external_exports.number().finite(),
+    default: external_exports.number().finite()
+  }).strict();
+  var ControlValues = external_exports.array(external_exports.union([external_exports.number().finite(), external_exports.array(external_exports.number().finite()).min(1)])).min(2);
+  var ControlChannel = external_exports.discriminatedUnion("target", [
+    external_exports.object({ target: external_exports.literal("bone"), id: Id, prop: BoneProp, values: ControlValues }).strict(),
+    external_exports.object({ target: external_exports.literal("slot"), id: Id, prop: external_exports.literal("alpha"), values: ControlValues }).strict(),
+    external_exports.object({ target: external_exports.literal("deform"), id: Id, prop: external_exports.literal("vertices"), values: ControlValues }).strict()
+  ]);
+  var ControlBinding = external_exports.object({
+    id: Id,
+    axes: external_exports.array(external_exports.object({ control: Id, keys: external_exports.array(external_exports.number().finite()).min(2).max(32) }).strict()).min(1).max(2),
+    /** Flattened grid, first axis varies fastest. Linear / bilinear interpolation. */
+    channels: external_exports.array(ControlChannel).min(1)
+  }).strict();
   var Reference = external_exports.object({
     src: external_exports.string(),
     opacity: external_exports.number().min(0).max(1).default(0.5),
@@ -49633,7 +49659,9 @@ ${parts.join("\n")}
     ik: external_exports.array(IkConstraint).default([]),
     transform: external_exports.array(TransformConstraint).default([]),
     path: external_exports.array(PathConstraint).default([]),
-    animations: external_exports.array(Animation)
+    animations: external_exports.array(Animation),
+    controls: external_exports.array(RigControl).optional(),
+    controlBindings: external_exports.array(ControlBinding).optional()
   });
   var RigDocument = external_exports.preprocess((input) => {
     const v2 = input?.version;
@@ -49708,6 +49736,8 @@ ${parts.join("\n")}
     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((b2) => b2.id));
     const assets = new Map(doc.assets.map((a2) => [a2.id, a2]));
     const slots = new Set(doc.slots.map((s2) => s2.id));
@@ -49734,6 +49764,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 +49799,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}"`);
     }
@@ -49777,13 +49812,47 @@ ${parts.join("\n")}
       for (const b2 of c2.bones) if (!bones.has(b2)) errs.push(`path "${c2.id}": unknown bone "${b2}"`);
       if (!slots.has(c2.target)) errs.push(`path "${c2.id}": unknown target slot "${c2.target}"`);
     }
+    const controls = new Map((doc.controls ?? []).map((c2) => [c2.id, c2]));
+    const driven = /* @__PURE__ */ new Set();
+    for (const c2 of controls.values()) if (!(c2.min < c2.max && c2.default >= c2.min && c2.default <= c2.max))
+      errs.push(`control "${c2.id}": require min < max and default within range`);
+    for (const b2 of doc.controlBindings ?? []) {
+      const prefix = `control binding "${b2.id}"`;
+      if (new Set(b2.axes.map((a2) => a2.control)).size !== b2.axes.length) errs.push(`${prefix}: axes must use different controls`);
+      for (const axis of b2.axes) {
+        const c2 = controls.get(axis.control);
+        if (!c2) errs.push(`${prefix}: unknown control "${axis.control}"`);
+        else if (axis.keys[0] !== c2.min || axis.keys.at(-1) !== c2.max) errs.push(`${prefix}: keys must span the control's full range`);
+        if (axis.keys.some((v2, i2) => i2 > 0 && v2 <= axis.keys[i2 - 1])) errs.push(`${prefix}: keys must be strictly increasing`);
+      }
+      const count2 = b2.axes.reduce((n2, a2) => n2 * a2.keys.length, 1);
+      for (const ch of b2.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 !== count2) errs.push(`${prefix}: ${key} needs ${count2} 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 n2 = att.weights ? att.weights.reduce((s2, a2) => s2 + a2.length * 2, 0) : att.vertices.length;
+            if (ch.values.some((v2) => !Array.isArray(v2) || v2.length !== n2)) errs.push(`${prefix}: ${key} needs arrays of ${n2} offsets`);
+          }
+        } else {
+          if (!(ch.target === "bone" ? bones : slots).has(ch.id)) errs.push(`${prefix}: unknown ${ch.target} "${ch.id}"`);
+          if (ch.values.some((v2) => typeof v2 !== "number")) errs.push(`${prefix}: ${key} needs numeric values`);
+          if (ch.target === "slot" && ch.values.some((v2) => typeof v2 === "number" && (v2 < 0 || v2 > 1))) errs.push(`${prefix}: alpha must be in 0..1`);
+        }
+      }
+    }
     for (const a2 of doc.animations) {
       const tracks = /* @__PURE__ */ new Set();
       for (const t2 of a2.tracks) {
         const tid = trackId(t2);
         if (tracks.has(tid)) errs.push(`animation "${a2.id}": duplicate track ${tid}`);
         tracks.add(tid);
-        const known = t2.target === "bone" ? bones.has(t2.id) : t2.target === "slot" ? slots.has(t2.id) : t2.target === "deform" ? attachments.has(t2.id) : t2.target === "ik" ? iks.has(t2.id) : t2.target === "transform" ? transforms.has(t2.id) : t2.target === "path" ? paths.has(t2.id) : true;
+        if (driven.has(tid)) errs.push(`animation "${a2.id}": ${tid} is controlled by a binding; animate its control instead`);
+        const known = t2.target === "bone" ? bones.has(t2.id) : t2.target === "slot" ? slots.has(t2.id) : t2.target === "deform" ? attachments.has(t2.id) : t2.target === "ik" ? iks.has(t2.id) : t2.target === "transform" ? transforms.has(t2.id) : t2.target === "path" ? paths.has(t2.id) : t2.target === "control" ? controls.has(t2.id) : true;
         if (!known) errs.push(`animation "${a2.id}": unknown ${t2.target} "${t2.id}"`);
         const bound = t2.target === "deform" ? DEFORM_BOUNDS[t2.prop] : void 0;
         const att = t2.target === "deform" ? attachments.get(t2.id) : void 0;
@@ -49791,6 +49860,10 @@ ${parts.join("\n")}
         for (const k2 of t2.keys) {
           if (k2.t <= prev && prev >= 0) errs.push(`animation "${a2.id}" ${tid}: keys not strictly increasing`);
           if (k2.t > a2.duration) errs.push(`animation "${a2.id}" ${tid}: key at ${k2.t}s exceeds duration`);
+          if (t2.target === "control") {
+            const c2 = controls.get(t2.id);
+            if (typeof k2.v !== "number" || !Number.isFinite(k2.v) || c2 && (k2.v < c2.min || k2.v > c2.max)) errs.push(`animation "${a2.id}" ${tid}: control key outside its finite range`);
+          }
           if (t2.target === "slot" && t2.prop === "attachment") {
             if (k2.v !== null && typeof k2.v !== "string") errs.push(`animation "${a2.id}" ${tid}: attachment key must be an attachment id or null`);
             else if (typeof k2.v === "string") {
@@ -49829,6 +49902,52 @@ ${parts.join("\n")}
     return doc;
   }
 
+  // src/rig-controls.ts
+  function controlPose(doc, values) {
+    const out2 = /* @__PURE__ */ new Map();
+    for (const [id, value] of Object.entries(values)) {
+      const c2 = doc.controls?.find((c3) => c3.id === id);
+      if (!c2) throw new Error(`unknown control "${id}"`);
+      if (!Number.isFinite(value)) throw new Error(`control "${id}" must be finite`);
+      out2.set(`control:${id}:value`, Math.max(c2.min, Math.min(c2.max, value)));
+    }
+    return out2;
+  }
+  function bracket(keys, value) {
+    let i2 = 0;
+    while (i2 < keys.length - 2 && value > keys[i2 + 1]) i2++;
+    return [i2, Math.max(0, Math.min(1, (value - keys[i2]) / (keys[i2 + 1] - keys[i2])))];
+  }
+  function sampleBinding(binding, values) {
+    const [x2, u2] = bracket(binding.axes[0].keys, values[0]);
+    const [y2, v2] = binding.axes[1] ? bracket(binding.axes[1].keys, values[1]) : [0, 0];
+    const width = binding.axes[0].keys.length, a2 = y2 * width + x2;
+    const mix = (a3, b2, u3) => a3 + (b2 - a3) * u3;
+    return binding.channels.map((ch) => {
+      const read = (i2, j2) => j2 === void 0 ? ch.values[i2] : ch.values[i2][j2];
+      const at = (j2) => {
+        const top = mix(read(a2, j2), read(a2 + 1, j2), u2);
+        return binding.axes[1] ? mix(top, mix(read(a2 + width, j2), read(a2 + width + 1, j2), u2), v2) : 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 out2 = new Map(input), controls = new Map(doc.controls?.map((c2) => [c2.id, c2]));
+    for (const b2 of doc.controlBindings) {
+      const values = b2.axes.map((axis) => {
+        const c2 = controls.get(axis.control);
+        const value = input.get(`control:${c2.id}:value`) ?? c2.default;
+        if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`control "${c2.id}" must be finite`);
+        return Math.max(c2.min, Math.min(c2.max, value));
+      });
+      const sampled = sampleBinding(b2, values);
+      b2.channels.forEach((ch, i2) => out2.set(`${ch.target}:${ch.id}:${ch.prop}`, sampled[i2]));
+    }
+    return out2;
+  }
+
   // src/rig-anim.ts
   var DEG2 = Math.PI / 180;
   var named = {
@@ -49837,6 +49956,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 +49988,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,36 +50014,44 @@ ${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;
   }
   function restValue(doc, key) {
     const [target, id, prop] = key.split(":");
+    if (target === "control") return doc.controls?.find((c2) => c2.id === id)?.default ?? 0;
     if (target === "bone") return doc.bones.find((b2) => b2.id === id).transform[prop];
     if (target === "slot") {
       const s2 = doc.slots.find((s3) => s3.id === id);
@@ -50008,7 +50154,9 @@ ${parts.join("\n")}
       for (const k2 of kids.get(id) ?? []) stack.push(k2.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 b2 of boneOrder(doc)) {
       const s2 = localOf(doc, pose, b2);
@@ -50069,10 +50217,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 +50388,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 +50716,7 @@ ${parts.join("\n")}
   var AnimationState = class {
     constructor(sink, opts = {}) {
       this.sink = sink;
+      this.opts = opts;
       this.defaultMix = opts.mix ?? 0;
     }
     onEvent;
@@ -50558,11 +50741,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 +50761,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 +50791,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 +50879,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 +50919,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,17 +50958,63 @@ ${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());
     }
+    inputPose = /* @__PURE__ */ new Map();
+    controlOverrides = /* @__PURE__ */ new Map();
+    /** Manual inputs override animated controls until resetControls; values are clamped to declared ranges. */
+    setControls(values) {
+      this.controlOverrides = controlPose(this.doc, values);
+      this.setPose(this.inputPose);
+    }
+    resetControls() {
+      this.controlOverrides.clear();
+      this.setPose(this.inputPose);
+    }
     view = new Container();
     state;
     items = [];
+    beforePose = /* @__PURE__ */ new Set();
+    afterPose = /* @__PURE__ */ new Set();
+    clipPoints = /* @__PURE__ */ new Map();
     skel;
     textures;
     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();
+    /** Read-only render handles for in-page tools. Nodes remain owned by the player. */
+    get renderItems() {
+      return this.items;
+    }
+    /** Current document-space clipping polygons, keyed by path attachment id. */
+    get clipPolygons() {
+      return this.clipPoints;
+    }
+    /**
+     * Modify resolved control outputs before skeleton evaluation, constraints and skinning.
+     * Callbacks run in registration order, each with its own map. Change control inputs via setControls.
+     */
+    onBeforePose(callback) {
+      this.beforePose.add(callback);
+      return () => {
+        this.beforePose.delete(callback);
+      };
+    }
+    /** Subscribe after the base pose has been rebuilt. Return value removes the callback. */
+    onAfterPose(callback) {
+      this.afterPose.add(callback);
+      return () => {
+        this.afterPose.delete(callback);
+      };
+    }
+    /** Rebuild the current pose without advancing playback; useful for reversible overlays. */
+    refreshPose() {
+      this.setPose(this.inputPose);
+    }
     /** whole atlas page as a plain texture (identity uv mapping) for skinned meshes */
     pageTexture(tex) {
       let page = this.pages.get(tex.source);
@@ -50776,7 +51026,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 +51055,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();
@@ -50815,13 +51069,39 @@ ${parts.join("\n")}
     }
     /** Apply a pose (rest where silent) to the display objects. */
     setPose(pose) {
-      const skel = this.skel = evaluate(this.doc, pose);
+      this.inputPose = new Map(pose);
+      if (this.controlOverrides.size) pose = new Map([...pose, ...this.controlOverrides]);
+      this.clipPoints.clear();
+      const skel = this.skel = evaluate(this.doc, pose, this.beforePose);
+      pose = skel.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);
+        const polygon = points.flatMap((p2) => [p2.x, p2.y]);
+        this.clipPoints.set(id, polygon);
+        g2.clear().poly(polygon, 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,10 +51109,12 @@ ${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) {
+          it.node.setFromMatrix(m2.identity());
           const v2 = attachmentWorldVertices(skel, s2.id, it.att);
           const buf = it.skinned.mesh.geometry.getBuffer("aPosition");
           buf.data.set(v2);
@@ -50865,6 +51147,7 @@ ${parts.join("\n")}
           it.node.scale.y *= h2 / (this.textures.get(att.asset)?.height ?? h2);
         }
       }
+      for (const callback of this.afterPose) callback(this);
     }
     /** World-space bone positions — used by editor gizmos and renderPreview overlays */
     bonePositions() {
@@ -50912,7 +51195,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 +51240,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 +51248,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;