@energy8platform/golem 0.3.0 → 0.6.0

package/dist/lib/harness.js

@@ -49524,7 +49524,9 @@ ${parts.join("\n")}
     /** curve lengths for constant-speed positioning */
     lengths: external_exports.array(external_exports.number()).default([]),
     closed: external_exports.boolean().default(false),
-    constantSpeed: external_exports.boolean().default(true)
+    constantSpeed: external_exports.boolean().default(true),
+    /** Spine-style active clipping span in the posed draw order; end slot is inclusive. */
+    clipping: external_exports.object({ end: Id.optional() }).optional()
   });
   var Attachment = external_exports.discriminatedUnion("type", [RegionAttachment, MeshAttachment, PathAttachment]);
   var IkConstraint = external_exports.object({
@@ -49588,10 +49590,13 @@ ${parts.join("\n")}
     t: external_exports.number().nonnegative(),
     v: KeyValue,
     /** easing INTO the next key */
-    ease: Ease.default("ease_in_out")
+    ease: Ease.default("ease_in_out"),
+    /** Optional independent easing for numeric-array components (for example Spine RGBA curves). */
+    componentEase: external_exports.array(Ease).min(1).optional()
   });
   var Interpolation = { interpolation: external_exports.enum(["segment", "pchip"]).optional() };
   var Track = external_exports.discriminatedUnion("target", [
+    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) }),
@@ -49614,6 +49619,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),
@@ -49639,7 +49663,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;
@@ -49714,6 +49740,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));
@@ -49751,6 +49779,10 @@ ${parts.join("\n")}
         else if (a2.slot !== s2.id) errs.push(`slot "${s2.id}": attachment "${s2.attachment}" belongs to slot "${a2.slot}"`);
       }
     }
+    for (const a2 of doc.attachments) if (a2.type === "path" && a2.clipping) {
+      if (!a2.closed) errs.push(`attachment "${a2.id}": clipping path must be closed`);
+      if (a2.clipping.end && !slots.has(a2.clipping.end)) errs.push(`attachment "${a2.id}": unknown clipping end slot "${a2.clipping.end}"`);
+    }
     const vertexCount = (a2) => {
       if (a2.type === "region") return 4;
       if (a2.type === "mesh") return a2.uvs.length / 2;
@@ -49788,20 +49820,59 @@ ${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;
         let prev = -1;
         for (const k2 of t2.keys) {
+          if (k2.componentEase && (!Array.isArray(k2.v) || !k2.v.every((v2) => typeof v2 === "number") || k2.componentEase.length !== k2.v.length)) errs.push(`animation "${a2.id}" ${tid}: componentEase must match the numeric-array value length`);
           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") {
@@ -49840,6 +49911,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 = {
@@ -49914,8 +50031,8 @@ ${parts.join("\n")}
     }
     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);
+      const phase = (t2 - a2.t) / (b2.t - a2.t), av = a2.v, bv = b2.v;
+      return av.map((v2, k2) => v2 + ((bv[k2] ?? v2) - v2) * ease(a2.componentEase?.[k2] ?? a2.ease)(phase));
     }
     return a2.v;
   }
@@ -49943,6 +50060,7 @@ ${parts.join("\n")}
   }
   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);
@@ -50002,6 +50120,13 @@ ${parts.join("\n")}
     if (!parent) return local;
     if (bone.inherit === "normal") return mul(parent, local);
     const [tx, ty] = apply(parent, s2.x, s2.y);
+    if (bone.inherit === "noScale" || bone.inherit === "noScaleOrReflection") {
+      const r2 = s2.rotation * DEG2, x2 = parent.a * Math.cos(r2) + parent.c * Math.sin(r2), y2 = parent.b * Math.cos(r2) + parent.d * Math.sin(r2);
+      const length2 = Math.hypot(x2, y2), a2 = length2 > 1e-5 ? x2 / length2 : x2, b2 = length2 > 1e-5 ? y2 / length2 : y2;
+      const sign = bone.inherit === "noScale" && parent.a * parent.d - parent.b * parent.c < 0 ? -1 : 1;
+      const basis2 = { a: a2, b: b2, c: -b2 * sign, d: a2 * sign, tx: 0, ty: 0 };
+      return { ...mul(basis2, affineOf(0, 0, 0, s2.scaleX, s2.scaleY, s2.shearX, s2.shearY)), tx, ty };
+    }
     return { ...mul(inheritedParentLinear(bone, parent), { ...local, tx: 0, ty: 0 }), tx, ty };
   }
   var orderCache = /* @__PURE__ */ new WeakMap();
@@ -50034,18 +50159,20 @@ ${parts.join("\n")}
       shearY: num(pose, pk("bone", id, "shearY"), r2.shearY)
     };
   };
-  function updateSubtree(skel, root) {
+  function updateSubtree(skel, root, includeRoot = true) {
     const doc = skel.doc;
     const kids = /* @__PURE__ */ new Map();
     for (const b2 of doc.bones) if (b2.parent) (kids.get(b2.parent) ?? kids.set(b2.parent, []).get(b2.parent)).push(b2);
-    const stack = [root];
+    const stack = includeRoot ? [root] : (kids.get(root) ?? []).map((b2) => b2.id);
     while (stack.length) {
       const id = stack.pop(), b2 = boneOf(doc, id), st = skel.bones.get(id);
       st.world = boneWorldOf(b2, st, b2.parent ? skel.bones.get(b2.parent).world : void 0);
       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);
@@ -50070,6 +50197,23 @@ ${parts.join("\n")}
     }
     return skel;
   }
+  function slotClips(skel) {
+    const keyed = skel.pose.get(pk("drawOrder", "order", "order"));
+    const order = Array.isArray(keyed) ? keyed : [...skel.doc.slots].sort((a2, b2) => a2.z - b2.z).map((s2) => s2.id);
+    const masks = /* @__PURE__ */ new Map();
+    let active;
+    for (const id of order) {
+      const att = skel.attachment.get(id);
+      if (!active && att?.type === "path" && att.clipping) {
+        active = att;
+        continue;
+      }
+      if (active) masks.set(id, active.id);
+      if (active?.clipping?.end === id) active = void 0;
+    }
+    for (const s2 of skel.doc.slots) if (s2.clip) masks.set(s2.id, s2.clip);
+    return masks;
+  }
   var cnum = (skel, kind, id, prop, rest) => num(skel.pose, pk(kind, id, prop), typeof rest === "boolean" ? rest ? 1 : 0 : rest);
   var IDENTITY = { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 };
   var wrapRad = (r2) => r2 > Math.PI ? r2 - 2 * Math.PI : r2 < -Math.PI ? r2 + 2 * Math.PI : r2;
@@ -50279,7 +50423,8 @@ ${parts.join("\n")}
     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;
+    const handedness = tw.a * tw.d - tw.b * tw.c < 0 ? -1 : 1;
+    const offsetRotation = c2.rotation * DEG2 * (c2.local ? 1 : handedness), offsetShearY = c2.shearY * DEG2 * (c2.local ? 1 : handedness);
     for (const id of c2.bones) {
       const b2 = boneOf(skel.doc, id), st = skel.bones.get(id);
       if (c2.local) {
@@ -50441,6 +50586,7 @@ ${parts.join("\n")}
     const position = cnum(skel, "path", c2.id, "position", c2.position), spacing = cnum(skel, "path", c2.id, "spacing", c2.spacing);
     const tangents = c2.rotateMode === "tangent", scale = c2.rotateMode === "chainScale";
     const bones = c2.bones.map((id) => ({ b: boneOf(skel.doc, id), st: skel.bones.get(id) }));
+    const inputWorlds = bones.map(({ st }) => ({ ...st.world }));
     const spacesCount = tangents ? bones.length : bones.length + 1;
     const spaces = new Array(spacesCount).fill(0), worldLengths = [];
     let sum = 0;
@@ -50475,9 +50621,10 @@ ${parts.join("\n")}
       if (tw.a * tw.d - tw.b * tw.c < 0) offsetRotation = -offsetRotation;
     }
     let boneX = samples[0].x, boneY = samples[0].y;
+    const solvedWorlds = /* @__PURE__ */ new Map();
     for (let i2 = 0; i2 < bones.length; i2++) {
       const { b: b2, st } = bones[i2];
-      let w2 = { ...st.world };
+      let w2 = { ...inputWorlds[i2] };
       w2.tx += (boneX - w2.tx) * mixX;
       w2.ty += (boneY - w2.ty) * mixY;
       const next = samples[i2 + 1] ?? { x: 0, y: 0, angle: 0 };
@@ -50507,7 +50654,11 @@ ${parts.join("\n")}
         const cos = Math.cos(r2), sin = Math.sin(r2);
         w2 = { a: cos * a2 - sin * bb, b: sin * a2 + cos * bb, c: cos * cc - sin * d2, d: sin * cc + cos * d2, tx: w2.tx, ty: w2.ty };
       }
-      setEffectiveWorld(skel, b2, st, w2);
+      solvedWorlds.set(b2.id, w2);
+    }
+    for (const b2 of boneOrder(skel.doc)) {
+      const world = solvedWorlds.get(b2.id);
+      if (world) setEffectiveWorld(skel, b2, skel.bones.get(b2.id), world);
     }
   }
   function measuredPathLength(points, closed, lengths, constantSpeed) {
@@ -50536,9 +50687,14 @@ ${parts.join("\n")}
       case "onlyTranslation":
         return { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 };
       case "noRotationOrReflection": {
-        const lenX = Math.hypot(parent.a, parent.b) || 1;
+        const lenX = Math.hypot(parent.a, parent.b);
         const det = parent.a * parent.d - parent.b * parent.c;
-        return { a: lenX, b: 0, c: 0, d: Math.abs(det) / lenX, tx: 0, ty: 0 };
+        if (lenX * lenX <= 1e-4) {
+          const lenY = Math.hypot(parent.c, parent.d), ux3 = lenY ? parent.c / lenY : 0, uy3 = lenY ? parent.d / lenY : 0;
+          return { a: lenY * ux3 * ux3, b: lenY * ux3 * uy3, c: lenY * ux3 * uy3, d: lenY * uy3 * uy3, tx: 0, ty: 0 };
+        }
+        const ux2 = parent.a / lenX, uy2 = parent.b / lenX, sy = Math.abs(det) / lenX;
+        return { a: lenX * ux2 * ux2 + sy * uy2 * uy2, b: (lenX - sy) * ux2 * uy2, c: (lenX - sy) * ux2 * uy2, d: lenX * uy2 * uy2 + sy * ux2 * ux2, tx: 0, ty: 0 };
       }
       case "noScale":
       case "noScaleOrReflection": {
@@ -50564,7 +50720,16 @@ ${parts.join("\n")}
     st.scaleY = Math.hypot(lin.c, lin.d);
     st.shearX = 0;
     st.shearY = shortest(Math.atan2(lin.d, lin.c) / DEG2 - st.rotation - 90);
-    updateSubtree(skel, bone.id);
+    if (parent && (bone.inherit === "noScale" || bone.inherit === "noScaleOrReflection")) {
+      const direction = mul(invert({ ...parent, tx: 0, ty: 0 }), { ...world, tx: 0, ty: 0 });
+      st.rotation = Math.atan2(direction.b, direction.a) / DEG2;
+      st.scaleX = Math.hypot(world.a, world.b);
+      st.scaleY = Math.hypot(world.c, world.d);
+      const sign = bone.inherit === "noScale" && parent.a * parent.d - parent.b * parent.c < 0 ? -1 : 1;
+      st.shearY = shortest((Math.atan2(world.d, world.c) - Math.atan2(world.b, world.a)) / DEG2 * sign - 90);
+    }
+    st.world = world;
+    updateSubtree(skel, bone.id, false);
   }
   function attachmentWorldVertices(skel, slotId, att) {
     const deform = skel.pose.get(pk("deform", att.id, "vertices"));
@@ -50850,9 +51015,23 @@ ${parts.join("\n")}
       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();
@@ -50861,6 +51040,35 @@ ${parts.join("\n")}
     /** 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);
@@ -50915,8 +51123,12 @@ ${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] : []));
+      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 masks = slotClips(skel), clips = new Set(masks.values());
       for (const [id, g2] of this.clipGraphics) if (!clips.has(id)) {
         g2.destroy();
         this.clipGraphics.delete(id);
@@ -50933,7 +51145,9 @@ ${parts.join("\n")}
         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 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"));
@@ -50941,7 +51155,8 @@ ${parts.join("\n")}
       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;
+        const mask = masks.get(s2.id);
+        it.node.mask = mask ? this.clipGraphics.get(mask) ?? null : null;
         if (shown !== it.att || this.hidden.has(s2.id)) {
           it.node.visible = false;
           continue;
@@ -50954,6 +51169,7 @@ ${parts.join("\n")}
         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);
@@ -50986,6 +51202,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() {

package/dist/lib/interactive-bones.d.ts

@@ -0,0 +1,37 @@
+import type { RigPlayer } from "./rig-runtime";
+import type { PartTransform } from "./interactive-editor";
+export interface BoneEditPatch {
+    format: "golem.bone-edits";
+    version: 1;
+    documentId: string;
+    transforms: Record<string, PartTransform>;
+}
+export interface InteractiveBoneEditorOptions {
+    player: Pick<RigPlayer, "doc" | "onBeforePose" | "refreshPose">;
+    documentId: string;
+    onChange?: (patch: BoneEditPatch) => void;
+    onRender?: () => void;
+    historyLimit?: number;
+}
+/** Add bone offsets after expression controls, before constraints and native skinning. */
+export declare function createInteractiveBoneEditor(options: InteractiveBoneEditorOptions): {
+    getTransform: (id: string) => {
+        x: number;
+        y: number;
+        rotation: number;
+        scaleX: number;
+        scaleY: number;
+    };
+    exportPatch: () => BoneEditPatch;
+    validatePatch: (value: unknown) => BoneEditPatch;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    setTransform(id: string, value: Partial<PartTransform>): void;
+    importPatch(value: unknown): void;
+    reset(id?: string): void;
+    setVisible(value: boolean): void;
+    undo(): void;
+    redo(): void;
+    dispose(): void;
+};
+export type InteractiveBoneEditor = ReturnType<typeof createInteractiveBoneEditor>;

package/dist/lib/interactive-editor.d.ts

@@ -0,0 +1,80 @@
+import type { RigPlayer } from "./rig-runtime";
+export interface EditorPoint {
+    x: number;
+    y: number;
+}
+export interface PartTransform {
+    x: number;
+    y: number;
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+}
+export interface InteractiveEditPatch {
+    format: "golem.interactive-edits";
+    version: 1;
+    documentId: string;
+    transforms: Record<string, PartTransform>;
+}
+export interface EditorGroup {
+    id: string;
+    members: readonly string[];
+    pivotBone?: string;
+}
+export type InteractivePlayer = Pick<RigPlayer, "doc" | "view" | "world" | "renderItems" | "clipPolygons" | "onAfterPose" | "refreshPose">;
+export interface InteractiveEditorOptions {
+    player: InteractivePlayer;
+    /** Transparent overlay aligned with the player's rendered viewport. It is cleared by the editor. */
+    overlay: HTMLCanvasElement;
+    /** Host-defined stable rig fingerprint; mismatched patches are rejected. */
+    documentId: string;
+    groups?: readonly EditorGroup[];
+    /** Override when overlay backing pixels differ from the renderer's logical coordinates. */
+    screenToDocument?: (client: EditorPoint) => EditorPoint;
+    documentToOverlay?: (point: EditorPoint) => EditorPoint;
+    alphaFallback?: "skip" | "geometry";
+    onChange?: (patch: InteractiveEditPatch) => void;
+    onSelection?: (id: string | null) => void;
+    onHover?: (id: string | null) => void;
+    onError?: (error: Error) => void;
+    onGestureStart?: () => void;
+    /** Render the host scene after a manual refresh; never called from the pose hook. */
+    onRender?: () => void;
+    historyLimit?: number;
+}
+export interface EditorFrame {
+    id: string;
+    center: EditorPoint;
+    corners: EditorPoint[];
+    handles: {
+        name: string;
+        p: EditorPoint;
+    }[];
+}
+/** Embedded part editor. Source documents are never mutated; edits replay after every evaluated pose. */
+export declare function createInteractiveEditor(options: InteractiveEditorOptions): {
+    select: (id: string | null) => void;
+    hitTest: (p: EditorPoint) => string | null;
+    getFrame: (id: string) => EditorFrame | null;
+    getTransform: (id: string) => {
+        x: number;
+        y: number;
+        rotation: number;
+        scaleX: number;
+        scaleY: number;
+    };
+    readonly selection: string | null;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    exportPatch: () => InteractiveEditPatch;
+    setEnabled(value: boolean): void;
+    setVisible(value: boolean): void;
+    setTransform(id: string, value: Partial<PartTransform>): void;
+    reset(id?: string): void;
+    undo(): void;
+    redo(): void;
+    importPatch(value: unknown): void;
+    dispose(): void;
+};
+export type InteractiveEditor = ReturnType<typeof createInteractiveEditor>;
+export { createInteractiveBoneEditor, type BoneEditPatch, type InteractiveBoneEditorOptions } from "./interactive-bones";