@energy8platform/golem 0.2.1 → 0.5.0

package/dist/lib/runtime.js

@@ -1,5 +1,5 @@
 // src/rig-runtime.ts
-import { Container, Sprite, Mesh, MeshGeometry, MeshPlane, Texture, Matrix, Rectangle } from "pixi.js";
+import { Container, Sprite, Mesh, MeshGeometry, MeshPlane, Texture, Matrix, Rectangle, Graphics } from "pixi.js";
 
 // src/rig-format.ts
 import { z } from "zod";
@@ -48,7 +48,7 @@ function gridPositions(offsets, w, h, pivot, n, out = new Float32Array(2 * n * n
 var ID_RE = /^[a-z][a-z0-9_]*$/;
 var Id = z.string().regex(ID_RE, "snake_case id");
 var Ease = z.union([
-  z.enum(["linear", "step", "ease_in", "ease_out", "ease_in_out", "back_out", "elastic_out"]),
+  z.enum(["linear", "step", "ease_in", "ease_out", "ease_in_out", "minimum_jerk", "back_out", "elastic_out"]),
   // cubic-bezier control points, same semantics as CSS
   z.object({ bezier: z.tuple([z.number(), z.number(), z.number(), z.number()]) })
 ]);
@@ -80,6 +80,7 @@ var Asset = z.object({
   /** where this layer came from — provenance for agents */
   origin: z.object({
     sourceImage: z.string().optional(),
+    bboxSpace: z.enum(["source", "document"]).optional(),
     /** bbox in source image: [x, y, w, h] */
     bbox: z.tuple([z.number(), z.number(), z.number(), z.number()]).optional(),
     inpainted: z.boolean().default(false),
@@ -102,6 +103,8 @@ var Bone = z.object({
 var Slot = z.object({
   id: Id,
   bone: Id,
+  /** Closed path attachment used as a moving clipping mask. */
+  clip: Id.optional(),
   /** active attachment id; undefined = hidden */
   attachment: Id.optional(),
   alpha: z.number().min(0).max(1).default(1),
@@ -164,6 +167,8 @@ var IkConstraint = z.object({
   order: z.number().int().default(0),
   bones: z.array(Id).min(1),
   target: Id,
+  iterations: z.number().int().min(1).max(1e3).optional(),
+  tolerance: z.number().positive().optional(),
   mix: z.number().default(1),
   softness: z.number().default(0),
   bendPositive: z.boolean().default(true),
@@ -211,7 +216,7 @@ var BoneProp = z.enum(["x", "y", "rotation", "scaleX", "scaleY", "shearX", "shea
 var SlotProp = z.enum(["alpha", "attachment", "z", "color"]);
 var DeformProp = z.string().regex(/^(bulge|bend|sway|squash|p[0-2][0-2][xy]|vertices)$/, "deform prop must be bulge|bend|sway|squash|p<row><col>x|y|vertices");
 var IkProp = z.enum(["mix", "softness", "bendPositive", "compress", "stretch"]);
-var TransformProp = z.enum(["mixRotate", "mixX", "mixY", "mixScaleX", "mixScaleY", "mixShearY"]);
+var TransformProp = z.enum(["mixRotate", "mixX", "mixY", "mixScaleX", "mixScaleY", "mixShearY", "x", "y", "rotation", "scaleX", "scaleY", "shearY"]);
 var PathProp = z.enum(["position", "spacing", "mixRotate", "mixX", "mixY"]);
 var KeyValue = z.union([z.number(), z.string(), z.null(), z.array(z.number()), z.array(z.string())]);
 var Key = z.object({
@@ -220,14 +225,16 @@ var Key = z.object({
   /** easing INTO the next key */
   ease: Ease.default("ease_in_out")
 });
+var Interpolation = { interpolation: z.enum(["segment", "pchip"]).optional() };
 var Track = z.discriminatedUnion("target", [
-  z.object({ target: z.literal("bone"), id: Id, prop: BoneProp, keys: z.array(Key).min(1) }),
-  z.object({ target: z.literal("slot"), id: Id, prop: SlotProp, keys: z.array(Key).min(1) }),
-  z.object({ target: z.literal("deform"), id: Id, prop: DeformProp, keys: z.array(Key).min(1) }),
-  z.object({ target: z.literal("ik"), id: Id, prop: IkProp, keys: z.array(Key).min(1) }),
-  z.object({ target: z.literal("transform"), id: Id, prop: TransformProp, keys: z.array(Key).min(1) }),
-  z.object({ target: z.literal("path"), id: Id, prop: PathProp, keys: z.array(Key).min(1) }),
-  z.object({ target: z.literal("drawOrder"), id: Id.default("order"), prop: z.literal("order").default("order"), keys: z.array(Key).min(1) })
+  z.object({ target: z.literal("control"), id: Id, prop: z.literal("value"), ...Interpolation, keys: z.array(Key).min(1) }),
+  z.object({ target: z.literal("bone"), id: Id, prop: BoneProp, ...Interpolation, keys: z.array(Key).min(1) }),
+  z.object({ target: z.literal("slot"), id: Id, prop: SlotProp, ...Interpolation, keys: z.array(Key).min(1) }),
+  z.object({ target: z.literal("deform"), id: Id, prop: DeformProp, ...Interpolation, keys: z.array(Key).min(1) }),
+  z.object({ target: z.literal("ik"), id: Id, prop: IkProp, ...Interpolation, keys: z.array(Key).min(1) }),
+  z.object({ target: z.literal("transform"), id: Id, prop: TransformProp, ...Interpolation, keys: z.array(Key).min(1) }),
+  z.object({ target: z.literal("path"), id: Id, prop: PathProp, ...Interpolation, keys: z.array(Key).min(1) }),
+  z.object({ target: z.literal("drawOrder"), id: Id.default("order"), prop: z.literal("order").default("order"), ...Interpolation, keys: z.array(Key).min(1) })
 ]);
 var Event = z.object({
   t: z.number().nonnegative(),
@@ -243,6 +250,25 @@ var Animation = z.object({
   /** if generated from a preset — keep params so the agent can re-tune instead of re-keying */
   preset: z.object({ name: z.string(), params: z.record(z.unknown()) }).optional()
 });
+var RigControl = z.object({
+  id: Id,
+  label: z.string().optional(),
+  min: z.number().finite(),
+  max: z.number().finite(),
+  default: z.number().finite()
+}).strict();
+var ControlValues = z.array(z.union([z.number().finite(), z.array(z.number().finite()).min(1)])).min(2);
+var ControlChannel = z.discriminatedUnion("target", [
+  z.object({ target: z.literal("bone"), id: Id, prop: BoneProp, values: ControlValues }).strict(),
+  z.object({ target: z.literal("slot"), id: Id, prop: z.literal("alpha"), values: ControlValues }).strict(),
+  z.object({ target: z.literal("deform"), id: Id, prop: z.literal("vertices"), values: ControlValues }).strict()
+]);
+var ControlBinding = z.object({
+  id: Id,
+  axes: z.array(z.object({ control: Id, keys: z.array(z.number().finite()).min(2).max(32) }).strict()).min(1).max(2),
+  /** Flattened grid, first axis varies fastest. Linear / bilinear interpolation. */
+  channels: z.array(ControlChannel).min(1)
+}).strict();
 var Reference = z.object({
   src: z.string(),
   opacity: z.number().min(0).max(1).default(0.5),
@@ -268,7 +294,9 @@ var RigSchema = z.object({
   ik: z.array(IkConstraint).default([]),
   transform: z.array(TransformConstraint).default([]),
   path: z.array(PathConstraint).default([]),
-  animations: z.array(Animation)
+  animations: z.array(Animation),
+  controls: z.array(RigControl).optional(),
+  controlBindings: z.array(ControlBinding).optional()
 });
 var RigDocument = z.preprocess((input) => {
   const v = input?.version;
@@ -343,6 +371,8 @@ function validate(doc) {
   dup(doc.ik, "ik");
   dup(doc.transform, "transform");
   dup(doc.path, "path");
+  dup(doc.controls ?? [], "control");
+  dup(doc.controlBindings ?? [], "control binding");
   const bones = new Set(doc.bones.map((b) => b.id));
   const assets = new Map(doc.assets.map((a) => [a.id, a]));
   const slots = new Set(doc.slots.map((s) => s.id));
@@ -369,6 +399,10 @@ function validate(doc) {
     if (a.frame && !a.trim && !a.rotate && (a.frame[2] !== a.width || a.frame[3] !== a.height)) errs.push(`asset "${a.id}": frame size must equal width\xD7height (or declare trim/rotate)`);
   }
   for (const s of doc.slots) {
+    if (s.clip) {
+      const mask = attachments.get(s.clip);
+      if (mask?.type !== "path" || !mask.closed) errs.push(`slot "${s.id}": clip must name a closed path attachment`);
+    }
     if (!bones.has(s.bone)) errs.push(`slot "${s.id}": unknown bone "${s.bone}"`);
     if (s.attachment) {
       const a = attachments.get(s.attachment);
@@ -400,7 +434,8 @@ function validate(doc) {
     }
   }
   for (const c of doc.ik) {
-    if (c.bones.length > 2) errs.push(`ik "${c.id}": must have 1 or 2 bones`);
+    for (let i = 1; i < c.bones.length; i++) if (doc.bones.find((b) => b.id === c.bones[i])?.parent !== c.bones[i - 1])
+      errs.push(`ik "${c.id}": bones must form a contiguous parent-to-child chain`);
     for (const b of c.bones) if (!bones.has(b)) errs.push(`ik "${c.id}": unknown bone "${b}"`);
     if (!bones.has(c.target)) errs.push(`ik "${c.id}": unknown target bone "${c.target}"`);
   }
@@ -412,13 +447,47 @@ function validate(doc) {
     for (const b of c.bones) if (!bones.has(b)) errs.push(`path "${c.id}": unknown bone "${b}"`);
     if (!slots.has(c.target)) errs.push(`path "${c.id}": unknown target slot "${c.target}"`);
   }
+  const controls = new Map((doc.controls ?? []).map((c) => [c.id, c]));
+  const driven = /* @__PURE__ */ new Set();
+  for (const c of controls.values()) if (!(c.min < c.max && c.default >= c.min && c.default <= c.max))
+    errs.push(`control "${c.id}": require min < max and default within range`);
+  for (const b of doc.controlBindings ?? []) {
+    const prefix = `control binding "${b.id}"`;
+    if (new Set(b.axes.map((a) => a.control)).size !== b.axes.length) errs.push(`${prefix}: axes must use different controls`);
+    for (const axis of b.axes) {
+      const c = controls.get(axis.control);
+      if (!c) errs.push(`${prefix}: unknown control "${axis.control}"`);
+      else if (axis.keys[0] !== c.min || axis.keys.at(-1) !== c.max) errs.push(`${prefix}: keys must span the control's full range`);
+      if (axis.keys.some((v, i) => i > 0 && v <= axis.keys[i - 1])) errs.push(`${prefix}: keys must be strictly increasing`);
+    }
+    const count = b.axes.reduce((n, a) => n * a.keys.length, 1);
+    for (const ch of b.channels) {
+      const key = `${ch.target}.${ch.id}.${ch.prop}`;
+      if (driven.has(key)) errs.push(`${prefix}: channel ${key} already owned by a binding`);
+      driven.add(key);
+      if (ch.values.length !== count) errs.push(`${prefix}: ${key} needs ${count} grid values`);
+      if (ch.target === "deform") {
+        const att = attachments.get(ch.id);
+        if (!att || att.type === "region") errs.push(`${prefix}: vertices need a mesh or path attachment`);
+        else {
+          const n = att.weights ? att.weights.reduce((s, a) => s + a.length * 2, 0) : att.vertices.length;
+          if (ch.values.some((v) => !Array.isArray(v) || v.length !== n)) errs.push(`${prefix}: ${key} needs arrays of ${n} offsets`);
+        }
+      } else {
+        if (!(ch.target === "bone" ? bones : slots).has(ch.id)) errs.push(`${prefix}: unknown ${ch.target} "${ch.id}"`);
+        if (ch.values.some((v) => typeof v !== "number")) errs.push(`${prefix}: ${key} needs numeric values`);
+        if (ch.target === "slot" && ch.values.some((v) => typeof v === "number" && (v < 0 || v > 1))) errs.push(`${prefix}: alpha must be in 0..1`);
+      }
+    }
+  }
   for (const a of doc.animations) {
     const tracks = /* @__PURE__ */ new Set();
     for (const t of a.tracks) {
       const tid = trackId(t);
       if (tracks.has(tid)) errs.push(`animation "${a.id}": duplicate track ${tid}`);
       tracks.add(tid);
-      const known = t.target === "bone" ? bones.has(t.id) : t.target === "slot" ? slots.has(t.id) : t.target === "deform" ? attachments.has(t.id) : t.target === "ik" ? iks.has(t.id) : t.target === "transform" ? transforms.has(t.id) : t.target === "path" ? paths.has(t.id) : true;
+      if (driven.has(tid)) errs.push(`animation "${a.id}": ${tid} is controlled by a binding; animate its control instead`);
+      const known = t.target === "bone" ? bones.has(t.id) : t.target === "slot" ? slots.has(t.id) : t.target === "deform" ? attachments.has(t.id) : t.target === "ik" ? iks.has(t.id) : t.target === "transform" ? transforms.has(t.id) : t.target === "path" ? paths.has(t.id) : t.target === "control" ? controls.has(t.id) : true;
       if (!known) errs.push(`animation "${a.id}": unknown ${t.target} "${t.id}"`);
       const bound = t.target === "deform" ? DEFORM_BOUNDS[t.prop] : void 0;
       const att = t.target === "deform" ? attachments.get(t.id) : void 0;
@@ -426,6 +495,10 @@ function validate(doc) {
       for (const k of t.keys) {
         if (k.t <= prev && prev >= 0) errs.push(`animation "${a.id}" ${tid}: keys not strictly increasing`);
         if (k.t > a.duration) errs.push(`animation "${a.id}" ${tid}: key at ${k.t}s exceeds duration`);
+        if (t.target === "control") {
+          const c = controls.get(t.id);
+          if (typeof k.v !== "number" || !Number.isFinite(k.v) || c && (k.v < c.min || k.v > c.max)) errs.push(`animation "${a.id}" ${tid}: control key outside its finite range`);
+        }
         if (t.target === "slot" && t.prop === "attachment") {
           if (k.v !== null && typeof k.v !== "string") errs.push(`animation "${a.id}" ${tid}: attachment key must be an attachment id or null`);
           else if (typeof k.v === "string") {
@@ -464,6 +537,52 @@ function parse(input) {
   return doc;
 }
 
+// src/rig-controls.ts
+function controlPose(doc, values) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [id, value] of Object.entries(values)) {
+    const c = doc.controls?.find((c2) => c2.id === id);
+    if (!c) throw new Error(`unknown control "${id}"`);
+    if (!Number.isFinite(value)) throw new Error(`control "${id}" must be finite`);
+    out.set(`control:${id}:value`, Math.max(c.min, Math.min(c.max, value)));
+  }
+  return out;
+}
+function bracket(keys, value) {
+  let i = 0;
+  while (i < keys.length - 2 && value > keys[i + 1]) i++;
+  return [i, Math.max(0, Math.min(1, (value - keys[i]) / (keys[i + 1] - keys[i])))];
+}
+function sampleBinding(binding, values) {
+  const [x, u] = bracket(binding.axes[0].keys, values[0]);
+  const [y, v] = binding.axes[1] ? bracket(binding.axes[1].keys, values[1]) : [0, 0];
+  const width = binding.axes[0].keys.length, a = y * width + x;
+  const mix = (a2, b, u2) => a2 + (b - a2) * u2;
+  return binding.channels.map((ch) => {
+    const read = (i, j) => j === void 0 ? ch.values[i] : ch.values[i][j];
+    const at = (j) => {
+      const top = mix(read(a, j), read(a + 1, j), u);
+      return binding.axes[1] ? mix(top, mix(read(a + width, j), read(a + width + 1, j), u), v) : top;
+    };
+    return Array.isArray(ch.values[0]) ? ch.values[0].map((_, j) => at(j)) : at();
+  });
+}
+function resolveControls(doc, input) {
+  if (!doc.controlBindings?.length) return input;
+  const out = new Map(input), controls = new Map(doc.controls?.map((c) => [c.id, c]));
+  for (const b of doc.controlBindings) {
+    const values = b.axes.map((axis) => {
+      const c = controls.get(axis.control);
+      const value = input.get(`control:${c.id}:value`) ?? c.default;
+      if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`control "${c.id}" must be finite`);
+      return Math.max(c.min, Math.min(c.max, value));
+    });
+    const sampled = sampleBinding(b, values);
+    b.channels.forEach((ch, i) => out.set(`${ch.target}:${ch.id}:${ch.prop}`, sampled[i]));
+  }
+  return out;
+}
+
 // src/rig-anim.ts
 var DEG2 = Math.PI / 180;
 var named = {
@@ -472,6 +591,7 @@ var named = {
   ease_in: (t) => t * t,
   ease_out: (t) => 1 - (1 - t) * (1 - t),
   ease_in_out: (t) => t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2,
+  minimum_jerk: (t) => t * t * t * (10 + t * (-15 + 6 * t)),
   back_out: (t) => 1 + 2.70158 * (t - 1) ** 3 + 1.70158 * (t - 1) ** 2,
   elastic_out: (t) => t === 0 ? 0 : t === 1 ? 1 : 2 ** (-10 * t) * Math.sin((t * 10 - 0.75) * (2 * Math.PI / 3)) + 1
 };
@@ -503,7 +623,25 @@ function ease(spec) {
   return f;
 }
 var pk = (target, id, prop) => `${target}:${id}:${prop}`;
-function sample(track, t) {
+function smoothValue(track, i, t, component, loop) {
+  const k = track.keys, n = k.length;
+  const v = (j) => component === void 0 ? k[j].v : k[j].v[component];
+  const h = (j) => k[j + 1].t - k[j].t;
+  const d = (j) => (v(j + 1) - v(j)) / h(j);
+  const harmonic = (a, b, h0, h1) => a * b <= 0 ? 0 : 3 * (h0 + h1) / ((2 * h1 + h0) / a + (h1 + 2 * h0) / b);
+  const tangent = (j) => {
+    if (j === 0 || j === n - 1) {
+      if (loop && n > 2 && v(0) === v(n - 1) && k[0].ease !== "step" && k[n - 2].ease !== "step")
+        return harmonic(d(n - 2), d(0), h(n - 2), h(0));
+      return 0;
+    }
+    if (k[j - 1].ease === "step" || k[j].ease === "step") return 0;
+    return harmonic(d(j - 1), d(j), h(j - 1), h(j));
+  };
+  const u = (t - k[i].t) / h(i), u2 = u * u, u3 = u2 * u;
+  return (2 * u3 - 3 * u2 + 1) * v(i) + (u3 - 2 * u2 + u) * h(i) * tangent(i) + (-2 * u3 + 3 * u2) * v(i + 1) + (u3 - u2) * h(i) * tangent(i + 1);
+}
+function sample(track, t, loop = false) {
   const keys = track.keys;
   if (t <= keys[0].t) return keys[0].v;
   const last = keys[keys.length - 1];
@@ -511,36 +649,44 @@ function sample(track, t) {
   let i = 0;
   while (keys[i + 1].t <= t) i++;
   const a = keys[i], b = keys[i + 1];
+  if (a.ease === "step") return a.v;
   if (typeof a.v === "number" && typeof b.v === "number") {
+    if (track.interpolation === "pchip") return smoothValue(track, i, t, void 0, loop);
     const u = ease(a.ease)((t - a.t) / (b.t - a.t));
     return a.v + (b.v - a.v) * u;
   }
   if (Array.isArray(a.v) && Array.isArray(b.v) && typeof a.v[0] === "number") {
+    if (track.interpolation === "pchip") return a.v.map((_, j) => smoothValue(track, i, t, j, loop));
     const u = ease(a.ease)((t - a.t) / (b.t - a.t)), av = a.v, bv = b.v;
     return av.map((v, k) => v + ((bv[k] ?? v) - v) * u);
   }
   return a.v;
 }
 function poseOf(anim, t, out = /* @__PURE__ */ new Map()) {
-  for (const tr of anim.tracks) out.set(pk(tr.target, tr.id, tr.prop), sample(tr, t));
+  for (const tr of anim.tracks) out.set(pk(tr.target, tr.id, tr.prop), sample(tr, t, anim.loop && tr.keys[0].t === 0 && tr.keys.at(-1).t === anim.duration));
   return out;
 }
 function blendPoses(from, to, w, restOf) {
-  const out = new Map(to);
-  for (const [k, f] of from) {
-    const cur = to.get(k);
-    if (typeof f === "number") {
+  if (w >= 1) return new Map(to);
+  const out = /* @__PURE__ */ new Map();
+  for (const k of /* @__PURE__ */ new Set([...from.keys(), ...to.keys()])) {
+    const f = from.has(k) ? from.get(k) : restOf(k);
+    const cur = to.has(k) ? to.get(k) : restOf(k);
+    if (typeof f === "number" && !Array.isArray(cur)) {
       const target = typeof cur === "number" ? cur : restOf(k);
       out.set(k, f + (target - f) * w);
     } else if (Array.isArray(f) && typeof f[0] === "number") {
       const fv = f, tv = Array.isArray(cur) && typeof cur[0] === "number" ? cur : fv.map(() => 0);
       out.set(k, fv.map((v, i) => v + ((tv[i] ?? 0) - v) * w));
-    } else if (cur === void 0 && w < 1) out.set(k, f);
+    } else if (Array.isArray(cur) && typeof cur[0] === "number" && typeof f !== "string") {
+      out.set(k, cur.map((v) => v * w));
+    } else out.set(k, f ?? null);
   }
   return out;
 }
 function restValue(doc, key) {
   const [target, id, prop] = key.split(":");
+  if (target === "control") return doc.controls?.find((c) => c.id === id)?.default ?? 0;
   if (target === "bone") return doc.bones.find((b) => b.id === id).transform[prop];
   if (target === "slot") {
     const s = doc.slots.find((s2) => s2.id === id);
@@ -643,7 +789,9 @@ function updateSubtree(skel, root) {
     for (const k of kids.get(id) ?? []) stack.push(k.id);
   }
 }
-function evaluate(doc, pose) {
+function evaluate(doc, pose, modifiers) {
+  pose = resolveControls(doc, pose);
+  if (modifiers) for (const modify of modifiers) pose = modify(new Map(pose));
   const skel = { doc, pose, bones: /* @__PURE__ */ new Map(), attachment: /* @__PURE__ */ new Map() };
   for (const b of boneOrder(doc)) {
     const s = localOf(doc, pose, b);
@@ -704,10 +852,43 @@ function aimAt(skel, boneId, tx, ty, mix, compress = false, stretch = false, uni
   updateSubtree(skel, boneId);
 }
 var shortest = (deg) => ((deg + 180) % 360 + 360) % 360 - 180;
+function applyLongIk(skel, c, tx, ty, mix) {
+  const initial = c.bones.map((id) => ({ ...skel.bones.get(id) }));
+  const last = c.bones.at(-1), len = boneOf(skel.doc, last).length;
+  const end = () => apply(skel.bones.get(last).world, len, 0);
+  const tolerance = c.tolerance ?? 0.05;
+  const root = skel.bones.get(c.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", c.id, "bendPositive", c.bendPositive) > 0.5 ? 5 : -5;
+    updateSubtree(skel, last);
+  }
+  for (let iter = 0; iter < (c.iterations ?? 100); iter++) {
+    const e = end();
+    if (Math.hypot(e[0] - tx, e[1] - ty) <= tolerance) break;
+    for (let i = c.bones.length - 1; i >= 0; i--) {
+      const id = c.bones[i], b = boneOf(skel.doc, id), st = skel.bones.get(id), w = st.world, e2 = end();
+      const angle = wrapRad(Math.atan2(ty - w.ty, tx - w.tx) - Math.atan2(e2[1] - w.ty, e2[0] - w.tx));
+      const cos = Math.cos(angle), sin = Math.sin(angle);
+      setEffectiveWorld(skel, b, st, { ...w, a: cos * w.a - sin * w.b, b: sin * w.a + cos * w.b, c: cos * w.c - sin * w.d, d: sin * w.c + cos * w.d });
+    }
+  }
+  if (mix < 1) {
+    c.bones.forEach((id, i) => {
+      const st = skel.bones.get(id), from = initial[i];
+      for (const p of ["rotation", "shearX", "shearY"]) st[p] = from[p] + shortest(st[p] - from[p]) * mix;
+      for (const p of ["x", "y", "scaleX", "scaleY"]) st[p] = from[p] + (st[p] - from[p]) * mix;
+    });
+    updateSubtree(skel, c.bones[0]);
+  }
+}
 function applyIk(skel, c) {
   const mix = cnum(skel, "ik", c.id, "mix", c.mix);
   if (mix <= 0) return;
   const target = skel.bones.get(c.target).world;
+  if (c.bones.length > 2) {
+    applyLongIk(skel, c, target.tx, target.ty, mix);
+    return;
+  }
   const bendDir = cnum(skel, "ik", c.id, "bendPositive", c.bendPositive) > 0.5 ? 1 : -1;
   const compress = cnum(skel, "ik", c.id, "compress", c.compress) > 0.5, stretch = cnum(skel, "ik", c.id, "stretch", c.stretch) > 0.5;
   let softness = cnum(skel, "ik", c.id, "softness", c.softness);
@@ -842,6 +1023,7 @@ function applyTransformConstraint(skel, c) {
   const mixRotate = cnum(skel, "transform", c.id, "mixRotate", c.mixRotate), mixX = cnum(skel, "transform", c.id, "mixX", c.mixX), mixY = cnum(skel, "transform", c.id, "mixY", c.mixY);
   const mixScaleX = cnum(skel, "transform", c.id, "mixScaleX", c.mixScaleX), mixScaleY = cnum(skel, "transform", c.id, "mixScaleY", c.mixScaleY), mixShearY = cnum(skel, "transform", c.id, "mixShearY", c.mixShearY);
   if (!mixRotate && !mixX && !mixY && !mixScaleX && !mixScaleY && !mixShearY) return;
+  c = { ...c, ...Object.fromEntries(["x", "y", "rotation", "scaleX", "scaleY", "shearY"].map((p) => [p, cnum(skel, "transform", c.id, p, c[p])])) };
   const target = skel.bones.get(c.target), tw = target.world;
   const offsetRotation = c.rotation * DEG2, offsetShearY = c.shearY * DEG2;
   for (const id of c.bones) {
@@ -1169,6 +1351,7 @@ function regionSize(doc, att) {
 var AnimationState = class {
   constructor(sink, opts = {}) {
     this.sink = sink;
+    this.opts = opts;
     this.defaultMix = opts.mix ?? 0;
   }
   onEvent;
@@ -1193,11 +1376,18 @@ var AnimationState = class {
   }
   channel(id, loop, priority = 0) {
     const anim = this.sink.doc.animations.find((a) => a.id === id);
-    if (!anim) throw new Error(`unknown animation "${id}"`);
+    if (!anim) {
+      const message = `unknown animation "${id}"; available: ${this.sink.doc.animations.map((a) => a.id).join(", ")}`;
+      if (this.opts.missingAnimation === "throw") throw new Error(message);
+      (this.opts.onWarning ?? console.warn)(message);
+      return void 0;
+    }
     return { anim, time: 0, loop: loop ?? anim.loop, done: false, priority, fresh: true };
   }
   setBase(id, opts = {}) {
-    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);
@@ -1206,6 +1396,16 @@ var AnimationState = class {
   }
   play(id, opts = {}) {
     const ch = this.channel(id, opts.loop, opts.priority ?? 0);
+    if (!ch) {
+      this.main?.settle?.("interrupted");
+      for (const queued of this.queue) queued.settle?.("dropped");
+      this.main = void 0;
+      this.queue = [];
+      this.beginMix(opts.mix);
+      this.update(0);
+      opts.onComplete?.("dropped");
+      return Promise.resolve("dropped");
+    }
     const promise = new Promise((resolve) => {
       ch.settle = (r) => {
         ch.settle = void 0;
@@ -1226,7 +1426,10 @@ var AnimationState = class {
   /** 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() {
@@ -1351,7 +1554,7 @@ function atlasUV(asset, u, v, sourceW, sourceH) {
 var rgbOf = (c) => Math.round(c[0] * 255) << 16 | Math.round(c[1] * 255) << 8 | Math.round(c[2] * 255);
 var sameNumbers = (a, b) => a === b || a.length === b.length && a.every((v, i) => v === b[i]);
 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;
     parse(doc);
@@ -1390,12 +1593,26 @@ var RigPlayer = class {
       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();
@@ -1403,6 +1620,36 @@ var RigPlayer = class {
   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);
@@ -1414,7 +1661,7 @@ var RigPlayer = class {
     this.state.onEvent = opts.onEvent;
     return this.state.play(animId, {
       loop: opts.loop,
-      mix: opts.mix ?? 0,
+      mix: opts.mix,
       ifBusy: "interrupt",
       onComplete: (r) => {
         if (r === "completed") opts.onComplete?.();
@@ -1457,13 +1704,39 @@ var RigPlayer = class {
   }
   /** 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((s) => s.clip ? [s.clip] : []));
+    for (const [id, g] of this.clipGraphics) if (!clips.has(id)) {
+      g.destroy();
+      this.clipGraphics.delete(id);
+    }
+    for (const id of clips) {
+      const att = this.doc.attachments.find((a) => a.id === id);
+      if (att?.type !== "path" || !att.closed) continue;
+      let g = this.clipGraphics.get(id);
+      if (!g) {
+        g = new Graphics();
+        this.clipGraphics.set(id, g);
+        this.view.addChild(g);
+      }
+      const vertices = attachmentWorldVertices(skel, att.slot, att);
+      const n = Math.max(32, vertices.length * 4);
+      const points = samplePath(vertices, true, att.lengths, true, Array.from({ length: n }, (_, i) => i / n), true);
+      const polygon = points.flatMap((p) => [p.x, p.y]);
+      this.clipPoints.set(id, polygon);
+      g.clear().poly(polygon, true).fill(16777215);
+    }
     const m = new Matrix();
     const orderV = pose.get(pk("drawOrder", "order", "order"));
     const order = /* @__PURE__ */ new Map();
     if (Array.isArray(orderV)) orderV.forEach((id, i) => order.set(id, i));
     for (const it of this.items) {
       const s = it.slot, shown = skel.attachment.get(s.id);
+      it.node.mask = s.clip ? this.clipGraphics.get(s.clip) ?? null : null;
       if (shown !== it.att || this.hidden.has(s.id)) {
         it.node.visible = false;
         continue;
@@ -1476,6 +1749,7 @@ var RigPlayer = class {
       it.node.tint = rgbOf(color);
       it.node.zIndex = order.size ? order.get(s.id) ?? 0 : numOf(pose, pk("slot", s.id, "z"), s.z);
       if (it.skinned) {
+        it.node.setFromMatrix(m.identity());
         const v = attachmentWorldVertices(skel, s.id, it.att);
         const buf = it.skinned.mesh.geometry.getBuffer("aPosition");
         buf.data.set(v);
@@ -1508,6 +1782,7 @@ var RigPlayer = class {
         it.node.scale.y *= h / (this.textures.get(att.asset)?.height ?? h);
       }
     }
+    for (const callback of this.afterPose) callback(this);
   }
   /** World-space bone positions — used by editor gizmos and renderPreview overlays */
   bonePositions() {
@@ -1584,9 +1859,12 @@ export {
   RigPlayer,
   RigSymbol,
   atlasUV,
+  controlPose,
   createTextures,
   migrateV1,
   parse,
+  resolveControls,
+  sampleBinding,
   validate
 };
 //# sourceMappingURL=runtime.js.map