@energy8platform/golem 0.2.0 → 0.3.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,15 @@ 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("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(),
@@ -369,6 +375,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 +410,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}"`);
   }
@@ -472,6 +483,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 +515,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,31 +541,38 @@ 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;
 }
@@ -704,10 +741,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 +912,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 +1240,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 +1265,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 +1285,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 +1315,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() {
@@ -1311,6 +1403,7 @@ function hit(t, prev, cur, d, loop) {
 // src/rig-runtime.ts
 var DEG3 = Math.PI / 180;
 var MESH_GRID = 9;
+var GHOST_ALPHA = 0.5;
 async function createTextures(doc, loadSource) {
   const bySrc = /* @__PURE__ */ new Map(), out = /* @__PURE__ */ new Map();
   for (const a of doc.assets) {
@@ -1350,7 +1443,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);
@@ -1389,7 +1482,7 @@ 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());
   }
   view = new Container();
@@ -1400,6 +1493,9 @@ var RigPlayer = class {
   pages = /* @__PURE__ */ new Map();
   /** slots the editor hides; honoured by setPose */
   hidden = /* @__PURE__ */ new Set();
+  /** slots the editor has selected; setPose draws them at GHOST_ALPHA at least */
+  ghosts = /* @__PURE__ */ new Set();
+  clipGraphics = /* @__PURE__ */ new Map();
   /** whole atlas page as a plain texture (identity uv mapping) for skinned meshes */
   pageTexture(tex) {
     let page = this.pages.get(tex.source);
@@ -1411,7 +1507,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?.();
@@ -1440,6 +1536,10 @@ var RigPlayer = class {
     if (visible) this.hidden.delete(slotId);
     else this.hidden.add(slotId);
   }
+  /** Editor-only: draw these slots at GHOST_ALPHA at least, whatever the pose says (an empty list clears it). */
+  setGhostSlots(slotIds) {
+    this.ghosts = new Set(slotIds);
+  }
   /** Stop playback and immediately restore the complete setup pose. */
   stop() {
     this.state.stop();
@@ -1451,12 +1551,32 @@ 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] : []));
+    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);
+      g.clear().poly(points.flatMap((p) => [p.x, p.y]), 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;
@@ -1464,7 +1584,8 @@ var RigPlayer = class {
       it.node.visible = true;
       const colorV = pose.get(pk("slot", s.id, "color"));
       const color = Array.isArray(colorV) && typeof colorV[0] === "number" ? colorV : colorToArray(s.color);
-      it.node.alpha = numOf(pose, pk("slot", s.id, "alpha"), s.alpha) * color[3];
+      const alpha = numOf(pose, pk("slot", s.id, "alpha"), s.alpha) * color[3];
+      it.node.alpha = this.ghosts.has(s.id) ? Math.max(alpha, GHOST_ALPHA) : alpha;
       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) {