@energy8platform/golem 0.3.0 → 0.6.0

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

@@ -50,17 +50,17 @@ export declare const GateConfig: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         b: string;
         a: string;
-        during?: [number, number] | undefined;
         min?: number | undefined;
         max?: number | undefined;
+        during?: [number, number] | undefined;
         minRatio?: number | undefined;
         maxRatio?: number | undefined;
     }, {
         b: string;
         a: string;
-        during?: [number, number] | undefined;
         min?: number | undefined;
         max?: number | undefined;
+        during?: [number, number] | undefined;
         minRatio?: number | undefined;
         maxRatio?: number | undefined;
     }>, "many">>;
@@ -84,9 +84,9 @@ export declare const GateConfig: z.ZodObject<{
         bone: string;
         prop: "x" | "y" | "rotation";
         whenSlotVisible: string;
-        space?: "local" | "world" | undefined;
         min?: number | undefined;
         max?: number | undefined;
+        space?: "local" | "world" | undefined;
         required?: boolean | undefined;
     }>, "many">>;
     transitions: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -130,9 +130,9 @@ export declare const GateConfig: z.ZodObject<{
     distances: {
         b: string;
         a: string;
-        during?: [number, number] | undefined;
         min?: number | undefined;
         max?: number | undefined;
+        during?: [number, number] | undefined;
         minRatio?: number | undefined;
         maxRatio?: number | undefined;
     }[];
@@ -172,9 +172,9 @@ export declare const GateConfig: z.ZodObject<{
     distances?: {
         b: string;
         a: string;
-        during?: [number, number] | undefined;
         min?: number | undefined;
         max?: number | undefined;
+        during?: [number, number] | undefined;
         minRatio?: number | undefined;
         maxRatio?: number | undefined;
     }[] | undefined;
@@ -182,9 +182,9 @@ export declare const GateConfig: z.ZodObject<{
         bone: string;
         prop: "x" | "y" | "rotation";
         whenSlotVisible: string;
-        space?: "local" | "world" | undefined;
         min?: number | undefined;
         max?: number | undefined;
+        space?: "local" | "world" | undefined;
         required?: boolean | undefined;
     }[] | undefined;
     transitions?: {

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

@@ -8,8 +8,8 @@
  * - play/tick/stop are a thin wrapper over an AnimationState (see rig-state.ts) kept for simple consumers
  *   (harness, viewer). Games should drive `state` directly for queues, priorities and overlays.
  */
-import { Container, Texture } from "pixi.js";
-import { type RigDocument, type Asset } from "./rig-format";
+import { Container, Sprite, Mesh, MeshPlane, Texture } from "pixi.js";
+import { type RigDocument, type Slot, type Attachment, type Asset } from "./rig-format";
 import { type Pose, type Affine } from "./rig-anim";
 import { AnimationState, type PlayResult } from "./rig-state";
 /** vertices per axis of a lattice-deformed region's render mesh (8 segments) */
@@ -23,6 +23,22 @@ export interface PlayOptions {
     onComplete?: () => void;
     onEvent?: (name: string, payload?: Record<string, unknown>) => void;
 }
+export interface RigRenderItem {
+    att: Attachment;
+    slot: Slot;
+    node: Sprite | MeshPlane | Mesh;
+    /** lattice-deformed region */
+    lattice?: {
+        plane: MeshPlane;
+        offsets: Float64Array;
+        applied: Float64Array;
+    };
+    /** skinned mesh */
+    skinned?: {
+        mesh: Mesh;
+        positions: Float32Array;
+    };
+}
 /** Build the asset-id → Texture map, loading each `src` once and cutting atlas frames (with rotation and trim). */
 export declare function createTextures(doc: RigDocument, loadSource: (src: string) => Promise<Texture>): Promise<Map<string, Texture>>;
 /**
@@ -32,9 +48,17 @@ export declare function createTextures(doc: RigDocument, loadSource: (src: strin
 export declare function atlasUV(asset: Asset, u: number, v: number, sourceW: number, sourceH: number): [number, number];
 export declare class RigPlayer {
     doc: RigDocument;
+    private inputPose;
+    private controlOverrides;
+    /** Manual inputs override animated controls until resetControls; values are clamped to declared ranges. */
+    setControls(values: Record<string, number>): void;
+    resetControls(): void;
     readonly view: Container<import("pixi.js").ContainerChild>;
     readonly state: AnimationState;
     private items;
+    private beforePose;
+    private afterPose;
+    private clipPoints;
     private skel;
     private textures;
     private pages;
@@ -49,6 +73,19 @@ export declare class RigPlayer {
         missingAnimation?: "warn" | "throw";
         onWarning?: (message: string) => void;
     });
+    /** Read-only render handles for in-page tools. Nodes remain owned by the player. */
+    get renderItems(): readonly Readonly<RigRenderItem>[];
+    /** Current document-space clipping polygons, keyed by path attachment id. */
+    get clipPolygons(): ReadonlyMap<string, readonly number[]>;
+    /**
+     * 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: (pose: Pose) => Pose): () => void;
+    /** Subscribe after the base pose has been rebuilt. Return value removes the callback. */
+    onAfterPose(callback: (player: RigPlayer) => void): () => void;
+    /** Rebuild the current pose without advancing playback; useful for reversible overlays. */
+    refreshPose(): void;
     /** whole atlas page as a plain texture (identity uv mapping) for skinned meshes */
     private pageTexture;
     /** Replace whatever is playing (no queueing). Resolves when the animation completes or is replaced. */

package/dist/lib/runtime.d.ts

@@ -2,8 +2,10 @@
  * `@energy8platform/golem/runtime` — the browser half: play a rig document in PixiJS v8.
  * Depends on pixi.js (peer) and zod only; no node, no tools, no editor.
  */
-export { RigPlayer, createTextures, atlasUV, MESH_GRID, type PlayOptions } from "./rig-runtime";
+export { RigPlayer, createTextures, atlasUV, MESH_GRID, type PlayOptions, type RigRenderItem } from "./rig-runtime";
 export { RigSymbol, type RigSymbolOptions, type SymbolSize, type SymbolViewLike, type TickerLike } from "./rig-symbol";
 export { AnimationState, type PlayResult, type PoseSink } from "./rig-state";
 export { parse, validate, migrateV1, RigDocument as RigDocumentSchema } from "./rig-format";
 export type { RigDocument, Bone, Slot, Asset, Attachment, Animation, Track, Key } from "./rig-format";
+export type { RigControl, ControlBinding } from "./rig-format";
+export { controlPose, resolveControls, sampleBinding } from "./rig-controls";

package/dist/lib/runtime.js

@@ -159,7 +159,9 @@ var PathAttachment = z.object({
   /** curve lengths for constant-speed positioning */
   lengths: z.array(z.number()).default([]),
   closed: z.boolean().default(false),
-  constantSpeed: z.boolean().default(true)
+  constantSpeed: z.boolean().default(true),
+  /** Spine-style active clipping span in the posed draw order; end slot is inclusive. */
+  clipping: z.object({ end: Id.optional() }).optional()
 });
 var Attachment = z.discriminatedUnion("type", [RegionAttachment, MeshAttachment, PathAttachment]);
 var IkConstraint = z.object({
@@ -223,10 +225,13 @@ var Key = z.object({
   t: z.number().nonnegative(),
   v: KeyValue,
   /** easing INTO the next key */
-  ease: Ease.default("ease_in_out")
+  ease: Ease.default("ease_in_out"),
+  /** Optional independent easing for numeric-array components (for example Spine RGBA curves). */
+  componentEase: z.array(Ease).min(1).optional()
 });
 var Interpolation = { interpolation: z.enum(["segment", "pchip"]).optional() };
 var Track = z.discriminatedUnion("target", [
+  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) }),
@@ -249,6 +254,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),
@@ -274,7 +298,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;
@@ -349,6 +375,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));
@@ -386,6 +414,10 @@ function validate(doc) {
       else if (a.slot !== s.id) errs.push(`slot "${s.id}": attachment "${s.attachment}" belongs to slot "${a.slot}"`);
     }
   }
+  for (const a of doc.attachments) if (a.type === "path" && a.clipping) {
+    if (!a.closed) errs.push(`attachment "${a.id}": clipping path must be closed`);
+    if (a.clipping.end && !slots.has(a.clipping.end)) errs.push(`attachment "${a.id}": unknown clipping end slot "${a.clipping.end}"`);
+  }
   const vertexCount = (a) => {
     if (a.type === "region") return 4;
     if (a.type === "mesh") return a.uvs.length / 2;
@@ -423,20 +455,59 @@ 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;
       let prev = -1;
       for (const k of t.keys) {
+        if (k.componentEase && (!Array.isArray(k.v) || !k.v.every((v) => typeof v === "number") || k.componentEase.length !== k.v.length)) errs.push(`animation "${a.id}" ${tid}: componentEase must match the numeric-array value length`);
         if (k.t <= prev && prev >= 0) errs.push(`animation "${a.id}" ${tid}: keys not strictly increasing`);
         if (k.t > a.duration) errs.push(`animation "${a.id}" ${tid}: key at ${k.t}s exceeds duration`);
+        if (t.target === "control") {
+          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") {
@@ -475,6 +546,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 = {
@@ -549,8 +666,8 @@ function sample(track, t, loop = false) {
   }
   if (Array.isArray(a.v) && Array.isArray(b.v) && typeof a.v[0] === "number") {
     if (track.interpolation === "pchip") return a.v.map((_, 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);
+    const phase = (t - a.t) / (b.t - a.t), av = a.v, bv = b.v;
+    return av.map((v, k) => v + ((bv[k] ?? v) - v) * ease(a.componentEase?.[k] ?? a.ease)(phase));
   }
   return a.v;
 }
@@ -578,6 +695,7 @@ function blendPoses(from, to, w, restOf) {
 }
 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);
@@ -637,6 +755,13 @@ function boneWorldOf(bone, s, parent) {
   if (!parent) return local;
   if (bone.inherit === "normal") return mul(parent, local);
   const [tx, ty] = apply(parent, s.x, s.y);
+  if (bone.inherit === "noScale" || bone.inherit === "noScaleOrReflection") {
+    const r = s.rotation * DEG2, x = parent.a * Math.cos(r) + parent.c * Math.sin(r), y = parent.b * Math.cos(r) + parent.d * Math.sin(r);
+    const length = Math.hypot(x, y), a = length > 1e-5 ? x / length : x, b = length > 1e-5 ? y / length : y;
+    const sign = bone.inherit === "noScale" && parent.a * parent.d - parent.b * parent.c < 0 ? -1 : 1;
+    const basis2 = { a, b, c: -b * sign, d: a * sign, tx: 0, ty: 0 };
+    return { ...mul(basis2, affineOf(0, 0, 0, s.scaleX, s.scaleY, s.shearX, s.shearY)), tx, ty };
+  }
   return { ...mul(inheritedParentLinear(bone, parent), { ...local, tx: 0, ty: 0 }), tx, ty };
 }
 var orderCache = /* @__PURE__ */ new WeakMap();
@@ -669,18 +794,20 @@ var localOf = (doc, pose, b) => {
     shearY: num(pose, pk("bone", id, "shearY"), r.shearY)
   };
 };
-function updateSubtree(skel, root) {
+function updateSubtree(skel, root, includeRoot = true) {
   const doc = skel.doc;
   const kids = /* @__PURE__ */ new Map();
   for (const b of doc.bones) if (b.parent) (kids.get(b.parent) ?? kids.set(b.parent, []).get(b.parent)).push(b);
-  const stack = [root];
+  const stack = includeRoot ? [root] : (kids.get(root) ?? []).map((b) => b.id);
   while (stack.length) {
     const id = stack.pop(), b = boneOf(doc, id), st = skel.bones.get(id);
     st.world = boneWorldOf(b, st, b.parent ? skel.bones.get(b.parent).world : void 0);
     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);
@@ -705,6 +832,23 @@ function evaluate(doc, pose) {
   }
   return skel;
 }
+function slotClips(skel) {
+  const keyed = skel.pose.get(pk("drawOrder", "order", "order"));
+  const order = Array.isArray(keyed) ? keyed : [...skel.doc.slots].sort((a, b) => a.z - b.z).map((s) => s.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 s of skel.doc.slots) if (s.clip) masks.set(s.id, s.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 = (r) => r > Math.PI ? r - 2 * Math.PI : r < -Math.PI ? r + 2 * Math.PI : r;
@@ -914,7 +1058,8 @@ function applyTransformConstraint(skel, c) {
   if (!mixRotate && !mixX && !mixY && !mixScaleX && !mixScaleY && !mixShearY) return;
   c = { ...c, ...Object.fromEntries(["x", "y", "rotation", "scaleX", "scaleY", "shearY"].map((p) => [p, cnum(skel, "transform", c.id, p, c[p])])) };
   const target = skel.bones.get(c.target), tw = target.world;
-  const offsetRotation = c.rotation * DEG2, offsetShearY = c.shearY * DEG2;
+  const handedness = tw.a * tw.d - tw.b * tw.c < 0 ? -1 : 1;
+  const offsetRotation = c.rotation * DEG2 * (c.local ? 1 : handedness), offsetShearY = c.shearY * DEG2 * (c.local ? 1 : handedness);
   for (const id of c.bones) {
     const b = boneOf(skel.doc, id), st = skel.bones.get(id);
     if (c.local) {
@@ -1076,6 +1221,7 @@ function applyPathConstraint(skel, c) {
   const position = cnum(skel, "path", c.id, "position", c.position), spacing = cnum(skel, "path", c.id, "spacing", c.spacing);
   const tangents = c.rotateMode === "tangent", scale = c.rotateMode === "chainScale";
   const bones = c.bones.map((id) => ({ b: boneOf(skel.doc, id), st: skel.bones.get(id) }));
+  const inputWorlds = bones.map(({ st }) => ({ ...st.world }));
   const spacesCount = tangents ? bones.length : bones.length + 1;
   const spaces = new Array(spacesCount).fill(0), worldLengths = [];
   let sum = 0;
@@ -1110,9 +1256,10 @@ function applyPathConstraint(skel, c) {
     if (tw.a * tw.d - tw.b * tw.c < 0) offsetRotation = -offsetRotation;
   }
   let boneX = samples[0].x, boneY = samples[0].y;
+  const solvedWorlds = /* @__PURE__ */ new Map();
   for (let i = 0; i < bones.length; i++) {
     const { b, st } = bones[i];
-    let w = { ...st.world };
+    let w = { ...inputWorlds[i] };
     w.tx += (boneX - w.tx) * mixX;
     w.ty += (boneY - w.ty) * mixY;
     const next = samples[i + 1] ?? { x: 0, y: 0, angle: 0 };
@@ -1142,7 +1289,11 @@ function applyPathConstraint(skel, c) {
       const cos = Math.cos(r), sin = Math.sin(r);
       w = { a: cos * a - sin * bb, b: sin * a + cos * bb, c: cos * cc - sin * d, d: sin * cc + cos * d, tx: w.tx, ty: w.ty };
     }
-    setEffectiveWorld(skel, b, st, w);
+    solvedWorlds.set(b.id, w);
+  }
+  for (const b of boneOrder(skel.doc)) {
+    const world = solvedWorlds.get(b.id);
+    if (world) setEffectiveWorld(skel, b, skel.bones.get(b.id), world);
   }
 }
 function measuredPathLength(points, closed, lengths, constantSpeed) {
@@ -1171,9 +1322,14 @@ function inheritedParentLinear(bone, parent) {
     case "onlyTranslation":
       return { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 };
     case "noRotationOrReflection": {
-      const lenX = Math.hypot(parent.a, parent.b) || 1;
+      const lenX = Math.hypot(parent.a, parent.b);
       const det = parent.a * parent.d - parent.b * parent.c;
-      return { a: lenX, b: 0, c: 0, d: Math.abs(det) / lenX, tx: 0, ty: 0 };
+      if (lenX * lenX <= 1e-4) {
+        const lenY = Math.hypot(parent.c, parent.d), ux2 = lenY ? parent.c / lenY : 0, uy2 = lenY ? parent.d / lenY : 0;
+        return { a: lenY * ux2 * ux2, b: lenY * ux2 * uy2, c: lenY * ux2 * uy2, d: lenY * uy2 * uy2, tx: 0, ty: 0 };
+      }
+      const ux = parent.a / lenX, uy = parent.b / lenX, sy = Math.abs(det) / lenX;
+      return { a: lenX * ux * ux + sy * uy * uy, b: (lenX - sy) * ux * uy, c: (lenX - sy) * ux * uy, d: lenX * uy * uy + sy * ux * ux, tx: 0, ty: 0 };
     }
     case "noScale":
     case "noScaleOrReflection": {
@@ -1199,7 +1355,16 @@ function setEffectiveWorld(skel, bone, st, world) {
   st.scaleY = Math.hypot(lin.c, lin.d);
   st.shearX = 0;
   st.shearY = shortest(Math.atan2(lin.d, lin.c) / DEG2 - st.rotation - 90);
-  updateSubtree(skel, bone.id);
+  if (parent && (bone.inherit === "noScale" || bone.inherit === "noScaleOrReflection")) {
+    const direction = mul(invert({ ...parent, tx: 0, ty: 0 }), { ...world, tx: 0, ty: 0 });
+    st.rotation = Math.atan2(direction.b, direction.a) / DEG2;
+    st.scaleX = Math.hypot(world.a, world.b);
+    st.scaleY = Math.hypot(world.c, world.d);
+    const sign = bone.inherit === "noScale" && parent.a * parent.d - parent.b * parent.c < 0 ? -1 : 1;
+    st.shearY = shortest((Math.atan2(world.d, world.c) - Math.atan2(world.b, world.a)) / DEG2 * sign - 90);
+  }
+  st.world = world;
+  updateSubtree(skel, bone.id, false);
 }
 function attachmentWorldVertices(skel, slotId, att) {
   const deform = skel.pose.get(pk("deform", att.id, "vertices"));
@@ -1485,9 +1650,23 @@ var RigPlayer = class {
     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();
@@ -1496,6 +1675,35 @@ var RigPlayer = class {
   /** 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);
@@ -1550,8 +1758,12 @@ var RigPlayer = class {
   }
   /** 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((s) => s.clip ? [s.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, g] of this.clipGraphics) if (!clips.has(id)) {
       g.destroy();
       this.clipGraphics.delete(id);
@@ -1568,7 +1780,9 @@ var RigPlayer = class {
       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);
-      g.clear().poly(points.flatMap((p) => [p.x, p.y]), true).fill(16777215);
+      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"));
@@ -1576,7 +1790,8 @@ var RigPlayer = class {
     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;
+      const mask = masks.get(s.id);
+      it.node.mask = mask ? this.clipGraphics.get(mask) ?? null : null;
       if (shown !== it.att || this.hidden.has(s.id)) {
         it.node.visible = false;
         continue;
@@ -1589,6 +1804,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);
@@ -1621,6 +1837,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() {
@@ -1697,9 +1914,12 @@ export {
   RigPlayer,
   RigSymbol,
   atlasUV,
+  controlPose,
   createTextures,
   migrateV1,
   parse,
+  resolveControls,
+  sampleBinding,
   validate
 };
 //# sourceMappingURL=runtime.js.map