reframe-video 0.2.0 → 0.3.0

package/assets/sfx/LICENSE.md

@@ -10,6 +10,7 @@ Verified against each asset page's license field on 2026-06-11.
 | whoosh.wav (wind body), rise.wav (reversed slice) | [Air whoosh](https://opengameart.org/content/air-whoosh) | qubodup | CC0 |
 | whoosh.wav (transient layer: swish-9) | [Swishes Sound Pack](https://opengameart.org/content/swishes-sound-pack) | artisticdude | CC0 |
 | thud.wav (trimmed) | [Muffled Distant Explosion](https://opengameart.org/content/muffled-distant-explosion) | NenadSimic | CC0 |
+| footstep_001/002/003.ogg (footstep00/03/06) | [RPG Audio](https://kenney.nl/assets/rpg-audio) | Kenney (kenney.nl) | CC0 |
 | bgm-song21.mp3 | [Mysterious Ambience (song21)](https://opengameart.org/content/mysterious-ambience-song21) | cynicmusic (pixelsphere.org) | multi-licensed; used under its CC0 option |
 
 CC0 requires no attribution; this file records provenance anyway.

package/dist/bin.js

@@ -1044,6 +1044,32 @@ var init_devicePreset = __esm({
   }
 });
 
+// ../core/src/rig.ts
+var init_rig = __esm({
+  "../core/src/rig.ts"() {
+    "use strict";
+    init_dsl();
+  }
+});
+
+// ../core/src/characterPreset.ts
+var init_characterPreset = __esm({
+  "../core/src/characterPreset.ts"() {
+    "use strict";
+    init_dsl();
+    init_rig();
+  }
+});
+
+// ../core/src/figure.ts
+var init_figure = __esm({
+  "../core/src/figure.ts"() {
+    "use strict";
+    init_dsl();
+    init_rig();
+  }
+});
+
 // ../core/src/motionOps.ts
 var init_motionOps = __esm({
   "../core/src/motionOps.ts"() {
@@ -1262,6 +1288,9 @@ var init_src = __esm({
     init_path();
     init_presets();
     init_devicePreset();
+    init_rig();
+    init_characterPreset();
+    init_figure();
     init_motionOps();
     init_audio();
     init_evaluate();
@@ -1361,7 +1390,7 @@ function buildLogoSting(d) {
   const inks = d.paths.map(
     (p, i) => path({ id: `ink-${i}`, d: p.d, originX: vcx, originY: vcy, x: 0, y: 0, stroke: p.fill, strokeWidth: sw, progress: 0 })
   );
-  const rig = {
+  const rig2 = {
     group: "logo",
     center: [CX, CY],
     baseScale: fit,
@@ -1381,7 +1410,7 @@ function buildLogoSting(d) {
     ],
     timeline: seq(
       motionPreset(d.motion ?? "reveal-orbit", {
-        target: rig,
+        target: rig2,
         ...d.energy !== void 0 && { energy: d.energy },
         ...d.speed !== void 0 && { speed: d.speed },
         ...d.intensity !== void 0 && { intensity: d.intensity },

package/dist/browserEntry.js

@@ -458,8 +458,57 @@
         a[3] + (b[3] - a[3]) * u
       ]);
     }
+    if (looksLikePath(from) && looksLikePath(to)) {
+      const a = tokenizePath(from);
+      const b = tokenizePath(to);
+      if (a && b && morphCompatible(a, b)) return morphPath(a, b, u);
+      return u < 0.5 ? from : to;
+    }
     return to;
   }
+  var PATH_BODY = /^[\sMmLlHhVvCcSsQqTtAaZz0-9.,eE+-]+$/;
+  function looksLikePath(v) {
+    return typeof v === "string" && /^\s*[Mm]/.test(v) && PATH_BODY.test(v);
+  }
+  var PATH_TOKEN = /([MmLlHhVvCcSsQqTtAaZz])|(-?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?)/g;
+  function tokenizePath(d) {
+    const out = [];
+    let cur = null;
+    let m;
+    PATH_TOKEN.lastIndex = 0;
+    while (m = PATH_TOKEN.exec(d)) {
+      if (m[1]) out.push(cur = { cmd: m[1], nums: [] });
+      else if (m[2]) {
+        if (!cur) return null;
+        cur.nums.push(parseFloat(m[2]));
+      }
+    }
+    return out.length ? out : null;
+  }
+  function morphCompatible(a, b) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      const ca = a[i];
+      const cb = b[i];
+      if (ca.cmd !== cb.cmd || ca.nums.length !== cb.nums.length) return false;
+      if (ca.cmd === "A" || ca.cmd === "a") return false;
+    }
+    return true;
+  }
+  var fmtNum = (v) => {
+    const r = Number(v.toFixed(3));
+    return Object.is(r, -0) ? "0" : String(r);
+  };
+  function morphPath(a, b, u) {
+    let s = "";
+    for (let i = 0; i < a.length; i++) {
+      const an = a[i].nums;
+      const bn = b[i].nums;
+      s += (i ? " " : "") + a[i].cmd;
+      for (let j = 0; j < an.length; j++) s += " " + fmtNum(an[j] + (bn[j] - an[j]) * u);
+    }
+    return s;
+  }
 
   // ../core/src/evaluate.ts
   var IDENTITY = [1, 0, 0, 1, 0, 0];

package/dist/index.js

@@ -15,22 +15,22 @@ function locate(segCount, u) {
   return { i, t: scaled - i };
 }
 function controls(points, closed, i) {
-  const n = points.length;
+  const n3 = points.length;
   const at = (k) => {
-    if (closed) return points[(k % n + n) % n];
-    return points[Math.max(0, Math.min(n - 1, k))];
+    if (closed) return points[(k % n3 + n3) % n3];
+    return points[Math.max(0, Math.min(n3 - 1, k))];
   };
   return [at(i - 1), at(i), at(i + 1), at(i + 2)];
 }
 function segCountOf(points, closed) {
-  const n = points.length;
-  if (n < 2) return 0;
-  return closed ? n : n - 1;
+  const n3 = points.length;
+  if (n3 < 2) return 0;
+  return closed ? n3 : n3 - 1;
 }
 function pathPoint(points, closed, u, curviness = 1) {
-  const n = points.length;
-  if (n === 0) return [0, 0];
-  if (n === 1) return [points[0][0], points[0][1]];
+  const n3 = points.length;
+  if (n3 === 0) return [0, 0];
+  if (n3 === 1) return [points[0][0], points[0][1]];
   const segs = segCountOf(points, closed);
   const { i, t } = locate(segs, u);
   const [p0, p1, p2, p3] = controls(points, closed, i);
@@ -49,8 +49,8 @@ function pathPoint(points, closed, u, curviness = 1) {
   return [H(p0[0], p1[0], p2[0], p3[0]), H(p0[1], p1[1], p2[1], p3[1])];
 }
 function pathTangentAngle(points, closed, u, curviness = 1) {
-  const n = points.length;
-  if (n < 2) return 0;
+  const n3 = points.length;
+  if (n3 < 2) return 0;
   const segs = segCountOf(points, closed);
   const { i, t } = locate(segs, u);
   const [p0, p1, p2, p3] = controls(points, closed, i);
@@ -816,7 +816,7 @@ function applyOverlay(ir, overlay, layer, report, baseNodeIds) {
       );
       continue;
     }
-    const index = ir.nodes.findIndex((n) => n.id === id);
+    const index = ir.nodes.findIndex((n3) => n3.id === id);
     if (index < 0) {
       orphan(
         `removeNodes.${id}`,
@@ -1263,9 +1263,434 @@ function devicePreset(name, opts = {}) {
   );
 }
 
+// ../core/src/rig.ts
+var DEFAULT_LINE = "#FFE3D2";
+var DEFAULT_FILL = "#0E1424";
+var LINE_W = 5;
+var GLOW_W = 16;
+var K = 0.5523;
+var n = (v) => Number(v.toFixed(2));
+function capsulePath(hw, len) {
+  const yT = hw;
+  const yB = Math.max(hw, len - hw);
+  const k = hw * K;
+  return `M ${n(-hw)} ${n(yT)} C ${n(-hw)} ${n(yT - k)} ${n(-k)} ${n(yT - hw)} 0 ${n(yT - hw)} C ${n(k)} ${n(yT - hw)} ${n(hw)} ${n(yT - k)} ${n(hw)} ${n(yT)} L ${n(hw)} ${n(yB)} C ${n(hw)} ${n(yB + k)} ${n(k)} ${n(yB + hw)} 0 ${n(yB + hw)} C ${n(-k)} ${n(yB + hw)} ${n(-hw)} ${n(yB + k)} ${n(-hw)} ${n(yB)} Z`;
+}
+function ovalPath(a, b, cx = 0, cy = 0) {
+  const ka = n(a * K), kb = n(b * K);
+  const t = n(cy - b), bo = n(cy + b), c = n(cy), A = n(a), L = n(-a), X = n(cx);
+  return `M ${X} ${t} C ${n(cx + ka)} ${t} ${n(cx + A)} ${n(cy - kb)} ${n(cx + A)} ${c} C ${n(cx + A)} ${n(cy + kb)} ${n(cx + ka)} ${bo} ${X} ${bo} C ${n(cx - ka)} ${bo} ${n(cx + L)} ${n(cy + kb)} ${n(cx + L)} ${c} C ${n(cx + L)} ${n(cy - kb)} ${n(cx - ka)} ${t} ${X} ${t} Z`;
+}
+function boneShape(jointId, bone, o) {
+  if (bone.shape) return bone.shape;
+  const len = bone.length ?? 0;
+  if (len <= 0) return [];
+  const d = capsulePath((bone.width ?? 20) / 2, len);
+  const nodes = [];
+  if (o.glow) nodes.push(path({ id: `${jointId}-glow`, d, x: 0, y: 0, fill: "none", stroke: o.glow, strokeWidth: GLOW_W, opacity: 0.18 }));
+  nodes.push(path({ id: `${jointId}-shape`, d, x: 0, y: 0, fill: o.fill, stroke: o.color, strokeWidth: LINE_W }));
+  return nodes;
+}
+function buildBone(bone, id, o) {
+  const jointId = `${id}-${bone.name}`;
+  return group(
+    { id: jointId, x: bone.at[0], y: bone.at[1], rotation: bone.rotation ?? 0 },
+    [...boneShape(jointId, bone, o), ...(bone.children ?? []).map((c) => buildBone(c, id, o))]
+  );
+}
+function rig(root, opts = {}) {
+  const id = opts.id ?? "rig";
+  const o = { color: opts.color ?? DEFAULT_LINE, fill: opts.fill ?? DEFAULT_FILL, glow: opts.glow };
+  return group(
+    { id, x: opts.x ?? 0, y: opts.y ?? 0, scale: opts.scale ?? 1, opacity: opts.opacity ?? 1 },
+    [buildBone(root, id, o)]
+  );
+}
+function rigPose(id, pose) {
+  const out = {};
+  for (const [name, deg] of Object.entries(pose)) out[`${id}-${name}`] = { rotation: deg };
+  return out;
+}
+function poseTo(id, pose, opts = {}) {
+  const tweens = Object.entries(pose).map(
+    ([name, deg]) => tween(`${id}-${name}`, { rotation: deg }, { duration: opts.duration ?? 0.5, ease: opts.ease ?? "easeInOutCubic" })
+  );
+  return opts.stagger ? stagger(opts.stagger, ...tweens) : par(...tweens);
+}
+function ikReach(upper, lower, dx, dy, flip = false) {
+  const D = Math.hypot(dx, dy);
+  const cos2 = Math.max(-1, Math.min(1, (D * D - upper * upper - lower * lower) / (2 * upper * lower)));
+  const theta2 = (flip ? -1 : 1) * Math.acos(cos2);
+  const vx = -lower * Math.sin(theta2);
+  const vy = upper + lower * Math.cos(theta2);
+  const theta1 = Math.atan2(dy, dx) - Math.atan2(vy, vx);
+  const deg = (r) => r * 180 / Math.PI;
+  return [deg(theta1), deg(theta2)];
+}
+function humanoid(opts = {}) {
+  const line2 = opts.color ?? DEFAULT_LINE;
+  const fill = opts.fill ?? DEFAULT_FILL;
+  const glow = opts.glow;
+  const blob = (jid, a, b, cy) => {
+    const d = ovalPath(a, b, 0, cy);
+    const nodes = [];
+    if (glow) nodes.push(path({ id: `${jid}-glow`, d, x: 0, y: 0, fill: "none", stroke: glow, strokeWidth: GLOW_W, opacity: 0.18 }));
+    nodes.push(path({ id: `${jid}-shape`, d, x: 0, y: 0, fill, stroke: line2, strokeWidth: LINE_W }));
+    return nodes;
+  };
+  const id = opts.id ?? "rig";
+  const root = {
+    name: "chest",
+    at: [0, 0],
+    shape: blob(`${id}-chest`, 44, 62, 22),
+    children: [
+      { name: "head", at: [0, -42], rotation: 0, shape: blob(`${id}-head`, 40, 42, -34) },
+      { name: "armUpperL", at: [-42, -20], length: 60, width: 20, rotation: 10, children: [
+        { name: "armLowerL", at: [0, 60], length: 56, width: 16, rotation: 8 }
+      ] },
+      { name: "armUpperR", at: [42, -20], length: 60, width: 20, rotation: -10, children: [
+        { name: "armLowerR", at: [0, 60], length: 56, width: 16, rotation: -8 }
+      ] },
+      { name: "legUpperL", at: [-20, 76], length: 76, width: 26, rotation: 3, children: [
+        { name: "legLowerL", at: [0, 76], length: 72, width: 22, rotation: -2 }
+      ] },
+      { name: "legUpperR", at: [20, 76], length: 76, width: 26, rotation: -3, children: [
+        { name: "legLowerR", at: [0, 76], length: 72, width: 22, rotation: 2 }
+      ] }
+    ]
+  };
+  return rig(root, opts);
+}
+
+// ../core/src/characterPreset.ts
+var CHARACTER_PRESET_NAMES = ["walk", "run", "jump", "dance", "wave", "cheer"];
+var THIGH = 76;
+var SHIN = 72;
+var clamp012 = (x) => Math.max(0, Math.min(1, x));
+function makeRng2(seed) {
+  let a = seed >>> 0 || 2654435769;
+  return () => {
+    a = a + 1831565813 | 0;
+    let t = Math.imul(a ^ a >>> 15, 1 | a);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+var dur2 = (base, sp) => base / sp;
+function ctx2(o) {
+  const rand = makeRng2((o.seed ?? 0) + 1);
+  return {
+    g: o.target,
+    label: o.label,
+    e: clamp012(o.energy ?? 0.5),
+    sp: Math.max(0.25, o.speed ?? 1),
+    cycles: Math.max(1, Math.round(o.cycles ?? 4)),
+    facing: o.facing ?? 1,
+    at: o.at ?? [0, 0],
+    travel: o.travel,
+    rand,
+    jit: (amp) => (rand() - 0.5) * 2 * amp
+  };
+}
+var round = (v) => Math.round(v * 1e3) / 1e3;
+function footPos(p, stride, lift) {
+  p = (p % 1 + 1) % 1;
+  if (p < 0.5) {
+    const u2 = p / 0.5;
+    return [stride * (1 - 2 * u2), 138];
+  }
+  const u = (p - 0.5) / 0.5;
+  return [-stride + 2 * stride * u, 138 - Math.sin(Math.PI * u) * lift];
+}
+function gaitPose(ph, stride, lift, armSwing, facing) {
+  const fl = footPos(ph, stride, lift);
+  const fr = footPos(ph + 0.5, stride, lift);
+  const [hipL, kneeL] = ikReach(THIGH, SHIN, facing * fl[0], fl[1], facing < 0);
+  const [hipR, kneeR] = ikReach(THIGH, SHIN, facing * fr[0], fr[1], facing < 0);
+  const swing = Math.cos(2 * Math.PI * ph);
+  return {
+    legUpperL: round(hipL),
+    legLowerL: round(kneeL),
+    legUpperR: round(hipR),
+    legLowerR: round(kneeR),
+    armUpperR: round(-10 - armSwing * swing),
+    armLowerR: -16,
+    armUpperL: round(10 + armSwing * swing),
+    armLowerL: 16
+  };
+}
+function gait(c, run) {
+  const stride = (run ? 34 : 24) + (run ? 40 : 30) * c.e + c.jit(3);
+  const lift = run ? 40 : 26;
+  const armSwing = (run ? 26 : 16) + 20 * c.e;
+  const halfDur = (run ? 0.26 : 0.42) + c.jit(0.02);
+  const lean = run ? c.facing * -6 : 0;
+  const steps = c.cycles * 2;
+  const d = dur2(halfDur, c.sp);
+  const intro = dur2(0.16, c.sp);
+  const keys = [];
+  for (let k = 0; k <= steps; k++) {
+    const pose = { ...gaitPose(k / 2, stride, lift, armSwing, c.facing), chest: lean };
+    keys.push(poseTo(c.g, pose, { duration: k === 0 ? intro : d, ease: k === 0 ? "easeOutQuad" : "linear" }));
+  }
+  const total = intro + steps * d;
+  const travel = c.travel ?? stride * 2;
+  const children = [seq(...keys)];
+  if (travel !== 0) {
+    children.push(tween(c.g, { x: c.at[0] + c.facing * travel * c.cycles }, { duration: total, ease: "linear", label: "travel" }));
+  }
+  return beat(run ? "run" : "walk", {}, [par(...children)]);
+}
+function jumpBeat(c) {
+  const h = 120 + 150 * c.e;
+  const [y0] = [c.at[1]];
+  const CROUCH = { legUpperL: 18, legLowerL: 54, legUpperR: -18, legLowerR: 54, armUpperL: 28, armUpperR: -28 };
+  const LAUNCH = { legUpperL: 0, legLowerL: 0, legUpperR: 0, legLowerR: 0, armUpperL: 150, armUpperR: -150 };
+  const TUCK = { legUpperL: -28, legLowerL: 66, legUpperR: -28, legLowerR: 66, armUpperL: 124, armUpperR: -124 };
+  const REST = { legUpperL: 3, legLowerL: -2, legUpperR: -3, legLowerR: 2, armUpperL: 10, armLowerL: 8, armUpperR: -10, armLowerR: -8 };
+  const j = c.jit(0.03);
+  return beat("jump", {}, [
+    seq(
+      par(poseTo(c.g, CROUCH, { duration: dur2(0.24, c.sp), ease: "easeOutQuad" }), tween(c.g, { y: y0 + 26 }, { duration: dur2(0.24, c.sp), ease: "easeOutQuad" })),
+      par(poseTo(c.g, LAUNCH, { duration: dur2(0.22 + j, c.sp), ease: "easeOutCubic" }), tween(c.g, { y: y0 - h }, { duration: dur2(0.36, c.sp), ease: "easeOutCubic", label: "launch" })),
+      poseTo(c.g, TUCK, { duration: dur2(0.22, c.sp) }),
+      par(poseTo(c.g, CROUCH, { duration: dur2(0.28, c.sp), ease: "easeInQuad" }), tween(c.g, { y: y0 + 18 }, { duration: dur2(0.3, c.sp), ease: "easeInCubic", label: "land" })),
+      par(poseTo(c.g, REST, { duration: dur2(0.45, c.sp), ease: "easeOutBack" }), tween(c.g, { y: y0 }, { duration: dur2(0.45, c.sp), ease: "easeOutBack" }))
+    )
+  ]);
+}
+function danceBeat(c) {
+  const y0 = c.at[1];
+  const sway = 8 + 6 * c.e;
+  const armUp = 130 + 30 * c.e;
+  const A = { chest: sway, head: -sway * 0.5, armUpperR: -armUp, armLowerR: -20, armUpperL: 40, armLowerL: 30, legUpperL: 8, legUpperR: -2 };
+  const B = { chest: -sway, head: sway * 0.5, armUpperL: armUp, armLowerL: 20, armUpperR: -40, armLowerR: -30, legUpperL: 2, legUpperR: -8 };
+  const d = dur2(0.34, c.sp);
+  const keys = [];
+  for (let k = 0; k < c.cycles * 2; k++) {
+    const pose = k % 2 === 0 ? A : B;
+    keys.push(par(
+      poseTo(c.g, pose, { duration: d, ease: "easeInOutQuad" }),
+      tween(c.g, { y: y0 - (k % 2 === 0 ? 14 : 0) }, { duration: d, ease: "easeInOutQuad" })
+    ));
+  }
+  keys.push(tween(c.g, { y: y0 }, { duration: d }));
+  return beat("dance", {}, [seq(...keys)]);
+}
+function waveBeat(c) {
+  const n3 = 3 + Math.round(c.rand() * 2);
+  const amp = 16 + 10 * c.e;
+  const steps = [poseTo(c.g, { armUpperR: -150, armLowerR: -24 }, { duration: dur2(0.4, c.sp), ease: "easeOutBack" })];
+  for (let k = 0; k < n3; k++) {
+    steps.push(poseTo(c.g, { armLowerR: -24 + (k % 2 === 0 ? amp : -amp) }, { duration: dur2(0.22, c.sp), ease: "easeInOutQuad" }));
+  }
+  steps.push(poseTo(c.g, { armUpperR: -10, armLowerR: -8 }, { duration: dur2(0.4, c.sp), ease: "easeInOutCubic" }));
+  return beat("wave", {}, [seq(...steps)]);
+}
+function cheerBeat(c) {
+  const y0 = c.at[1];
+  const UP = { armUpperL: 152, armLowerL: 8, armUpperR: -152, armLowerR: -8 };
+  const d = dur2(0.3, c.sp);
+  const keys = [poseTo(c.g, UP, { duration: dur2(0.35, c.sp), ease: "easeOutBack" })];
+  for (let k = 0; k < c.cycles; k++) {
+    keys.push(par(tween(c.g, { y: y0 - 28 }, { duration: d, ease: "easeOutQuad" }), poseTo(c.g, { armUpperL: 160, armUpperR: -160 }, { duration: d })));
+    keys.push(par(tween(c.g, { y: y0 }, { duration: d, ease: "easeInQuad" }), poseTo(c.g, { armUpperL: 145, armUpperR: -145 }, { duration: d })));
+  }
+  return beat("cheer", {}, [seq(...keys)]);
+}
+function characterPreset(name, opts) {
+  const c = ctx2(opts);
+  let tl;
+  switch (name) {
+    case "walk":
+      tl = gait(c, false);
+      break;
+    case "run":
+      tl = gait(c, true);
+      break;
+    case "jump":
+      tl = jumpBeat(c);
+      break;
+    case "dance":
+      tl = danceBeat(c);
+      break;
+    case "wave":
+      tl = waveBeat(c);
+      break;
+    case "cheer":
+      tl = cheerBeat(c);
+      break;
+    default: {
+      const _exhaustive = name;
+      throw new Error(`unknown characterPreset "${_exhaustive}"`);
+    }
+  }
+  return c.label && tl.kind === "beat" ? { ...tl, name: c.label } : tl;
+}
+
+// ../core/src/figure.ts
+var K2 = 0.5523;
+var n2 = (v) => Number(v.toFixed(2));
+function limb(a, b, y0, y1) {
+  const ka = n2(a * K2), kb = n2(b * K2);
+  return `M ${-a} ${y0} C ${-a} ${n2(y0 - ka)} ${-ka} ${n2(y0 - a)} 0 ${n2(y0 - a)} C ${ka} ${n2(y0 - a)} ${a} ${n2(y0 - ka)} ${a} ${y0} L ${b} ${y1} C ${b} ${n2(y1 + kb)} ${kb} ${n2(y1 + b)} 0 ${n2(y1 + b)} C ${-kb} ${n2(y1 + b)} ${-b} ${n2(y1 + kb)} ${-b} ${y1} Z`;
+}
+function rrect(a, b, y0, y1, r) {
+  return `M ${n2(-a + r)} ${y0} L ${n2(a - r)} ${y0} Q ${a} ${y0} ${a} ${n2(y0 + r)} L ${b} ${n2(y1 - r)} Q ${b} ${y1} ${n2(b - r)} ${y1} L ${n2(-b + r)} ${y1} Q ${-b} ${y1} ${-b} ${n2(y1 - r)} L ${-a} ${n2(y0 + r)} Q ${-a} ${y0} ${n2(-a + r)} ${y0} Z`;
+}
+function darken(hex, f) {
+  const h = hex.replace("#", "");
+  const v = parseInt(h.length === 3 ? [...h].map((c) => c + c).join("") : h, 16);
+  const ch = (s) => Math.max(0, Math.min(255, Math.round((v >> s & 255) * (1 - f))));
+  const hx = (x) => x.toString(16).padStart(2, "0");
+  return `#${hx(ch(16))}${hx(ch(8))}${hx(ch(0))}`;
+}
+var DEF = {
+  clean: { skin: "#E9B58E", hair: "#2B313F", top: "#E86C4A", pants: "#39425C", shoe: "#20242F", accent: "#E86C4A" },
+  cute: { skin: "#FFD2A6", hair: "#5B4636", top: "#FF7E5F", pants: "#3E6F8E", shoe: "#272B38", accent: "#FF7E5F" }
+};
+function resolvePal(style, p = {}) {
+  const d = DEF[style];
+  const accent = p.accent ?? d.accent;
+  const top = p.top ?? (style === "clean" ? accent : d.top);
+  const skin = p.skin ?? d.skin;
+  const hair = p.hair ?? d.hair;
+  const pants = p.pants ?? d.pants;
+  const shoe = p.shoe ?? d.shoe;
+  return {
+    skin,
+    skinSh: darken(skin, 0.12),
+    hair,
+    hairSh: darken(hair, 0.14),
+    top,
+    topSh: darken(top, 0.12),
+    pants,
+    pantsSh: darken(pants, 0.14),
+    shoe,
+    shoeSh: darken(shoe, 0.22),
+    eye: "#2B313F",
+    cheek: "#FF9E7E",
+    white: "#FFFFFF",
+    mouth: "#8A4233"
+  };
+}
+var fp = (id, d, fill, stroke, sw = 0, opacity = 1) => path({ id, d, x: 0, y: 0, fill, opacity, ...stroke && sw > 0 ? { stroke, strokeWidth: sw } : {} });
+function cleanParts(p, face) {
+  const HC = -42;
+  return {
+    upperArm: (j) => [fp(`${j}-sleeve`, limb(12, 10, 2, 58), p.top)],
+    forearm: (j) => [
+      fp(`${j}-elbow`, ovalPath(10, 10, 0, 3), p.skin),
+      fp(`${j}-fore`, limb(10, 8, 2, 48), p.skin),
+      fp(`${j}-hand`, ovalPath(11, 12, 0, 50), p.skin)
+    ],
+    thigh: (j) => [fp(`${j}-thigh`, limb(15, 13, 2, 72), p.pants)],
+    shin: (j) => [
+      fp(`${j}-knee`, ovalPath(13, 13, 0, 2), p.pants),
+      fp(`${j}-shin`, limb(13, 11, 2, 62), p.pants),
+      fp(`${j}-shoe`, ovalPath(15, 9, 4, 67), p.shoe)
+    ],
+    torso: (j) => [
+      fp(`${j}-shadow`, rrect(38, 26, -28, 52, 20), p.topSh),
+      fp(`${j}-top`, rrect(40, 27, -30, 52, 22), p.top),
+      fp(`${j}-pelvis`, rrect(29, 24, 46, 104, 14), p.pants)
+    ],
+    head: (j) => [
+      fp(`${j}-neck`, rrect(9, 9, 2, 22, 5), p.skin),
+      fp(`${j}-skin`, ovalPath(42, 46, 0, HC), p.skin),
+      fp(`${j}-hair`, ovalPath(44, 27, 0, HC - 31), p.hair),
+      fp(`${j}-hairL`, ovalPath(8, 14, -39, HC - 18), p.hair),
+      fp(`${j}-hairR`, ovalPath(8, 14, 39, HC - 18), p.hair),
+      ...face ? [fp(`${j}-eyeL`, ovalPath(5, 7, -14, HC + 2), p.eye), fp(`${j}-eyeR`, ovalPath(5, 7, 14, HC + 2), p.eye)] : []
+    ]
+  };
+}
+var CUTE_HAIR = "M -64 -54 C -78 -96 -50 -126 0 -126 C 50 -126 78 -96 64 -54 C 60 -34 48 -28 41 -33 C 35 -54 23 -60 9 -60 C 3 -60 -3 -60 -9 -60 C -23 -60 -35 -54 -41 -33 C -48 -28 -60 -34 -64 -54 Z";
+function cuteParts(p, face) {
+  const HC = -50;
+  return {
+    upperArm: (j) => [fp(`${j}-sleeve`, limb(15, 13, 2, 58), p.top, p.topSh, 2.5)],
+    forearm: (j) => [
+      fp(`${j}-elbow`, ovalPath(12, 12, 0, 3), p.skin, p.skinSh, 2.5),
+      fp(`${j}-fore`, limb(12, 10, 2, 46), p.skin, p.skinSh, 2.5),
+      fp(`${j}-hand`, ovalPath(13, 14, 0, 50), p.skin, p.skinSh, 2.5)
+    ],
+    thigh: (j) => [fp(`${j}-thigh`, limb(19, 16, 2, 72), p.pants, p.pantsSh, 2.5)],
+    shin: (j) => [
+      fp(`${j}-knee`, ovalPath(16, 16, 0, 2), p.pants, p.pantsSh, 2.5),
+      fp(`${j}-shin`, limb(15, 12, 2, 60), p.pants, p.pantsSh, 2.5),
+      fp(`${j}-shoe`, ovalPath(18, 11, 5, 66), p.shoe, darken(p.shoe, 0.25), 2.5)
+    ],
+    torso: (j) => [
+      fp(`${j}-shadow`, rrect(40, 34, -18, 52, 16), p.topSh),
+      fp(`${j}-top`, rrect(42, 35, -20, 52, 18), p.top, p.topSh, 2.5),
+      fp(`${j}-pelvis`, rrect(36, 30, 46, 104, 16), p.pants, p.pantsSh, 2.5)
+    ],
+    head: (j) => [
+      fp(`${j}-neck`, ovalPath(15, 12, 0, 12), p.skinSh),
+      fp(`${j}-skin`, ovalPath(42, 46, 0, HC + 4), p.skin, p.skinSh, 2.5),
+      fp(`${j}-cheekL`, ovalPath(11, 8, -40, HC + 22), p.cheek, void 0, 0, 0.5),
+      fp(`${j}-cheekR`, ovalPath(11, 8, 40, HC + 22), p.cheek, void 0, 0, 0.5),
+      fp(`${j}-hair`, CUTE_HAIR, p.hair, p.hairSh, 2),
+      ...face ? [
+        fp(`${j}-eyeL`, ovalPath(10, 13, -25, HC + 8), p.eye),
+        fp(`${j}-eyeR`, ovalPath(10, 13, 25, HC + 8), p.eye),
+        fp(`${j}-glL`, ovalPath(3.4, 3.4, -28, HC + 3), p.white),
+        fp(`${j}-glR`, ovalPath(3.4, 3.4, 22, HC + 3), p.white),
+        path({ id: `${j}-mouth`, d: "M -15 0 Q 0 15 15 0", x: 0, y: HC + 28, fill: "none", stroke: p.mouth, strokeWidth: 5 })
+      ] : []
+    ]
+  };
+}
+function buildSkeleton(id, S) {
+  const arm = (side, x, r1, r2) => ({
+    name: `armUpper${side}`,
+    at: [x, -14],
+    length: 60,
+    width: 0,
+    rotation: r1,
+    shape: S.upperArm(`${id}-armUpper${side}`),
+    children: [{ name: `armLower${side}`, at: [0, 60], length: 56, width: 0, rotation: r2, shape: S.forearm(`${id}-armLower${side}`) }]
+  });
+  const leg = (side, x, r1, r2) => ({
+    name: `legUpper${side}`,
+    at: [x, 76],
+    length: 76,
+    width: 0,
+    rotation: r1,
+    shape: S.thigh(`${id}-legUpper${side}`),
+    children: [{ name: `legLower${side}`, at: [0, 76], length: 72, width: 0, rotation: r2, shape: S.shin(`${id}-legLower${side}`) }]
+  });
+  return {
+    name: "chest",
+    at: [0, 0],
+    shape: S.torso(`${id}-chest`),
+    children: [
+      { name: "head", at: [0, -42], rotation: 0, shape: S.head(`${id}-head`) },
+      arm("L", -40, 8, 6),
+      arm("R", 40, -8, -6),
+      leg("L", -20, 3, -2),
+      leg("R", 20, -3, 2)
+    ]
+  };
+}
+function figure(opts = {}) {
+  const style = opts.style ?? "clean";
+  const pal = resolvePal(style, opts.palette);
+  const face = opts.face ?? true;
+  const id = opts.id ?? "figure";
+  const parts = style === "clean" ? cleanParts(pal, face) : cuteParts(pal, face);
+  const rigOpts = { id };
+  if (opts.x !== void 0) rigOpts.x = opts.x;
+  if (opts.y !== void 0) rigOpts.y = opts.y;
+  if (opts.scale !== void 0) rigOpts.scale = opts.scale;
+  if (opts.opacity !== void 0) rigOpts.opacity = opts.opacity;
+  return rig(buildSkeleton(id, parts), rigOpts);
+}
+
 // ../core/src/motionOps.ts
 var MOTION_OPS = ["rotate", "zoom", "ken-burns", "slide-in", "fade", "draw-on", "pulse"];
-var clamp012 = (n) => Math.max(0, Math.min(1, n));
+var clamp013 = (n3) => Math.max(0, Math.min(1, n3));
 function settleEase2(e) {
   return e < 0.34 ? "easeOutCubic" : e < 0.67 ? "easeOutBack" : "easeOutElastic";
 }
@@ -1283,7 +1708,7 @@ function fromVec2(from, dist) {
 }
 var motionOpLabel = (name, target) => `op-${name}-${target}`;
 function motionOp(name, target, opts = {}) {
-  const e = clamp012(opts.energy ?? 0.5);
+  const e = clamp013(opts.energy ?? 0.5);
   const sp = Math.max(0.25, opts.speed ?? 1);
   const amt = opts.amount ?? 1;
   const b = { scale: 1, x: 0, y: 0, rotation: 0, ...opts.base };
@@ -1493,8 +1918,8 @@ function valueNoise(x, seed) {
   const b = hash01(i + 1, seed) * 2 - 1;
   return a + (b - a) * u;
 }
-function hash01(n, seed) {
-  let h = n * 374761393 + seed * 668265263 | 0;
+function hash01(n3, seed) {
+  let h = n3 * 374761393 + seed * 668265263 | 0;
   h = h ^ h >>> 13 | 0;
   h = Math.imul(h, 1274126177);
   h = (h ^ h >>> 16) >>> 0;
@@ -1587,8 +2012,8 @@ function isColor(v) {
 function parseColor(hex) {
   let h = hex.slice(1);
   if (h.length <= 4) h = [...h].map((c) => c + c).join("");
-  const n = parseInt(h.padEnd(8, "f"), 16);
-  return [n >>> 24 & 255, n >>> 16 & 255, n >>> 8 & 255, n & 255];
+  const n3 = parseInt(h.padEnd(8, "f"), 16);
+  return [n3 >>> 24 & 255, n3 >>> 16 & 255, n3 >>> 8 & 255, n3 & 255];
 }
 function formatColor([r, g, b, a]) {
   const hex = (v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, "0");
@@ -1608,19 +2033,68 @@ function lerpValue(from, to2, u) {
       a[3] + (b[3] - a[3]) * u
     ]);
   }
+  if (looksLikePath(from) && looksLikePath(to2)) {
+    const a = tokenizePath(from);
+    const b = tokenizePath(to2);
+    if (a && b && morphCompatible(a, b)) return morphPath(a, b, u);
+    return u < 0.5 ? from : to2;
+  }
   return to2;
 }
+var PATH_BODY = /^[\sMmLlHhVvCcSsQqTtAaZz0-9.,eE+-]+$/;
+function looksLikePath(v) {
+  return typeof v === "string" && /^\s*[Mm]/.test(v) && PATH_BODY.test(v);
+}
+var PATH_TOKEN = /([MmLlHhVvCcSsQqTtAaZz])|(-?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?)/g;
+function tokenizePath(d) {
+  const out = [];
+  let cur = null;
+  let m;
+  PATH_TOKEN.lastIndex = 0;
+  while (m = PATH_TOKEN.exec(d)) {
+    if (m[1]) out.push(cur = { cmd: m[1], nums: [] });
+    else if (m[2]) {
+      if (!cur) return null;
+      cur.nums.push(parseFloat(m[2]));
+    }
+  }
+  return out.length ? out : null;
+}
+function morphCompatible(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const ca = a[i];
+    const cb = b[i];
+    if (ca.cmd !== cb.cmd || ca.nums.length !== cb.nums.length) return false;
+    if (ca.cmd === "A" || ca.cmd === "a") return false;
+  }
+  return true;
+}
+var fmtNum = (v) => {
+  const r = Number(v.toFixed(3));
+  return Object.is(r, -0) ? "0" : String(r);
+};
+function morphPath(a, b, u) {
+  let s = "";
+  for (let i = 0; i < a.length; i++) {
+    const an = a[i].nums;
+    const bn = b[i].nums;
+    s += (i ? " " : "") + a[i].cmd;
+    for (let j = 0; j < an.length; j++) s += " " + fmtNum(an[j] + (bn[j] - an[j]) * u);
+  }
+  return s;
+}
 
 // ../core/src/evaluate.ts
 var IDENTITY = [1, 0, 0, 1, 0, 0];
-function multiply(m, n) {
+function multiply(m, n3) {
   return [
-    m[0] * n[0] + m[2] * n[1],
-    m[1] * n[0] + m[3] * n[1],
-    m[0] * n[2] + m[2] * n[3],
-    m[1] * n[2] + m[3] * n[3],
-    m[0] * n[4] + m[2] * n[5] + m[4],
-    m[1] * n[4] + m[3] * n[5] + m[5]
+    m[0] * n3[0] + m[2] * n3[1],
+    m[1] * n3[0] + m[3] * n3[1],
+    m[0] * n3[2] + m[2] * n3[3],
+    m[1] * n3[2] + m[3] * n3[3],
+    m[0] * n3[4] + m[2] * n3[5] + m[4],
+    m[1] * n3[4] + m[3] * n3[5] + m[5]
   ];
 }
 function localMatrix(x, y, rotationDeg, scale, scaleX = 1, scaleY = 1, skewXDeg = 0, skewYDeg = 0) {
@@ -1635,9 +2109,9 @@ function localMatrix(x, y, rotationDeg, scale, scaleX = 1, scaleY = 1, skewXDeg
   const tx = Math.tan(skewXDeg * Math.PI / 180);
   const ty = Math.tan(skewYDeg * Math.PI / 180);
   const R = [c, s, -s, c, 0, 0];
-  const K = [1, ty, tx, 1, 0, 0];
+  const K3 = [1, ty, tx, 1, 0, 0];
   const S = [scale * scaleX, 0, 0, scale * scaleY, 0, 0];
-  const m = multiply(R, multiply(K, S));
+  const m = multiply(R, multiply(K3, S));
   return [m[0], m[1], m[2], m[3], x, y];
 }
 var ANCHOR_FACTORS = {
@@ -1937,29 +2411,29 @@ function sketchToTimeline(sketch, nodeIds) {
   const steps = [];
   events.forEach((ev, i) => {
     const node = nodeIds[i % nodeIds.length];
-    const dur2 = Math.max(0.05, ev.t1 - ev.t0);
+    const dur3 = Math.max(0.05, ev.t1 - ev.t0);
     const ease = easeFor(ev.easing);
     let motion;
     switch (ev.kind) {
       case "enter":
-        motion = tween(node, { opacity: 1 }, { duration: dur2, ease });
+        motion = tween(node, { opacity: 1 }, { duration: dur3, ease });
         break;
       case "exit":
-        motion = tween(node, { opacity: 0 }, { duration: dur2, ease });
+        motion = tween(node, { opacity: 0 }, { duration: dur3, ease });
         break;
       case "emphasis": {
         const peak = 1 + Math.max(0.08, Math.min(0.5, ev.magnitude));
         motion = seq(
-          tween(node, { scale: peak }, { duration: dur2 / 2, ease: "easeOutCubic" }),
-          tween(node, { scale: 1 }, { duration: dur2 / 2, ease: "easeInOutQuad" })
+          tween(node, { scale: peak }, { duration: dur3 / 2, ease: "easeOutCubic" }),
+          tween(node, { scale: 1 }, { duration: dur3 / 2, ease: "easeInOutQuad" })
         );
         break;
       }
       case "scale":
-        motion = tween(node, { scale: 1 + Math.max(-0.5, Math.min(0.5, ev.magnitude)) }, { duration: dur2, ease });
+        motion = tween(node, { scale: 1 + Math.max(-0.5, Math.min(0.5, ev.magnitude)) }, { duration: dur3, ease });
         break;
       case "move":
-        motion = tween(node, { opacity: 1 }, { duration: dur2, ease });
+        motion = tween(node, { opacity: 1 }, { duration: dur3, ease });
         break;
     }
     steps.push(ev.t0 > 0 ? seq(wait(ev.t0), motion) : motion);
@@ -1967,6 +2441,7 @@ function sketchToTimeline(sketch, nodeIds) {
   return par(...steps);
 }
 export {
+  CHARACTER_PRESET_NAMES,
   DEFAULT_CROSSFADE,
   DEFAULT_FPS,
   DEFAULT_MOTIONPATH_DURATION,
@@ -1980,6 +2455,7 @@ export {
   SFX_DURATION,
   SceneValidationError,
   beat,
+  characterPreset,
   collectImageSrcs,
   compileComposition,
   compileScene,
@@ -1991,8 +2467,11 @@ export {
   deviceScreenCenter,
   ellipse,
   evaluate,
+  figure,
   formatComposeReport,
   group,
+  humanoid,
+  ikReach,
   image,
   isColor,
   lerpValue,
@@ -2003,14 +2482,18 @@ export {
   motionPreset,
   nodeParentMatrix,
   oscillate,
+  ovalPath,
   par,
   path,
   pathPoint,
   pathTangentAngle,
+  poseTo,
   rect,
   resolveAudioPlan,
   resolveCompositionAudioPlan,
   resolveEase,
+  rig,
+  rigPose,
   sampleBehavior,
   sampleProp,
   scene,

package/dist/types/characterPreset.d.ts

@@ -0,0 +1,39 @@
+/**
+ * characterPreset — a SEEDED motion generator for the humanoid rig. The
+ * character analog of `motionPreset`: `characterPreset(name, opts)` returns a
+ * `beat` (a TimelineIR) that drives a `humanoid()` rig's joints through a named
+ * performance (walk/run/jump/dance/wave/cheer). Same `(name, knobs, seed)` →
+ * identical IR; a different `seed` varies it within the family.
+ *
+ *   seq(characterPreset("walk", { target: "hero", at: [CX, BASE_Y], cycles: 4 }))
+ *
+ * Pure keyframe timeline (a beat can't hold behaviors): secondary motion is
+ * baked into poses; continuous idle stays the author's `oscillate`. Legs use the
+ * 2-bone `ikReach` solver (foot targets relative to the hip → natural knee bend);
+ * arms swing via FK. Assumes the `humanoid()` joint names.
+ */
+import type { TimelineIR } from "./ir.js";
+export declare const CHARACTER_PRESET_NAMES: readonly ["walk", "run", "jump", "dance", "wave", "cheer"];
+export type CharacterPresetName = (typeof CHARACTER_PRESET_NAMES)[number];
+export interface CharacterPresetOpts {
+    /** humanoid rig id — joints are `${target}-${name}`, outer group = `${target}`. */
+    target: string;
+    /** 0..1 — stride / swing / bounce / jump-height amplitude (default 0.5). */
+    energy?: number;
+    /** >0 — tempo; durations divide by it (default 1, min 0.25). */
+    speed?: number;
+    /** Deterministic within-family variation (default 0). */
+    seed?: number;
+    /** Repeats for cyclic motions walk/run/dance (default 4). */
+    cycles?: number;
+    /** 1 = faces/moves right (default 1). */
+    facing?: 1 | -1;
+    /** The rig's scene position — needed to translate the body (walk travel, jump lift). Default [0,0]. */
+    at?: [number, number];
+    /** px travelled per cycle for walk/run (default ~stride·2; 0 = walk in place). */
+    travel?: number;
+    /** Override the beat name (overlay address) — set this when the same preset is
+     * used more than once in a scene so the beat labels stay unique. */
+    label?: string;
+}
+export declare function characterPreset(name: CharacterPresetName, opts: CharacterPresetOpts): TimelineIR;

package/dist/types/figure.d.ts

@@ -0,0 +1,32 @@
+/**
+ * figure() — a parametric DRESSED character, the sibling of `humanoid()`. Same
+ * skeleton geometry (so `characterPreset` / `ikReach` / overlays apply unchanged),
+ * but each bone carries a coloured, designed flat shape instead of a neon capsule.
+ * Two styles — `clean` (corporate-flat, undraw register: one accent + neutrals,
+ * minimal face, slim adult proportions) and `cute` (mascot: big head, full face).
+ * Palette knobs re-skin it in one line; shadows are derived so a single `accent`
+ * recolours the whole figure.
+ *
+ *   figure({ id: "fig", style: "clean", palette: { accent: "#3B82F6" } })
+ *   characterPreset("walk", { target: "fig", at: [x, y] })   // drives it
+ */
+import type { NodeIR } from "./ir.js";
+import { type RigOpts } from "./rig.js";
+export type FigureStyle = "clean" | "cute";
+export interface FigurePalette {
+    skin?: string;
+    hair?: string;
+    top?: string;
+    pants?: string;
+    shoe?: string;
+    accent?: string;
+}
+export interface FigureOpts extends RigOpts {
+    /** "clean" (corporate-flat, default) | "cute" (mascot). */
+    style?: FigureStyle;
+    /** Colour overrides merged onto the per-style defaults. */
+    palette?: FigurePalette;
+    /** Draw minimal facial features (default true). `false` = faceless (pure undraw). */
+    face?: boolean;
+}
+export declare function figure(opts?: FigureOpts): NodeIR;

package/dist/types/index.d.ts

@@ -7,6 +7,9 @@ export { compileScene, type CompiledScene, type PropertySegment, type LabelSpan,
 export { pathPoint, pathTangentAngle, type Pt } from "./path.js";
 export { motionPreset, PRESET_NAMES, type PresetName, type PresetRig, type PresetOpts } from "./presets.js";
 export { devicePreset, deviceScreen, deviceScreenCenter, deviceBounds, DEVICE_PRESET_NAMES, type DevicePresetName, type DevicePresetOpts } from "./devicePreset.js";
+export { rig, rigPose, poseTo, ikReach, humanoid, ovalPath, type Bone, type RigOpts, type Pose, type HumanoidOpts } from "./rig.js";
+export { characterPreset, CHARACTER_PRESET_NAMES, type CharacterPresetName, type CharacterPresetOpts } from "./characterPreset.js";
+export { figure, type FigureStyle, type FigureOpts, type FigurePalette } from "./figure.js";
 export { motionOp, motionOpLabel, MOTION_OPS, type MotionOpName, type MotionOpOpts, type MotionOpResult } from "./motionOps.js";
 export { resolveAudioPlan, resolveCompositionAudioPlan, SFX_DURATION, type AudioPlan, type ResolvedCue, } from "./audio.js";
 export { evaluate, sampleProp, nodeParentMatrix, type DisplayList, type DisplayOp, type Mat2D, type ClipRegion, type TextAlign, type TextBaseline, } from "./evaluate.js";

package/dist/types/interpolate.d.ts

@@ -5,8 +5,9 @@ export declare function resolveEase(ease: Ease | undefined): EaseFn;
 export declare function isColor(v: PropValue): v is string;
 /**
  * Interpolate two prop values at progress u (already eased).
- * number↔number lerps, color↔color lerps in RGB, anything else switches
- * discretely at the start of the segment.
+ * number↔number lerps, color↔color lerps in RGB, two *compatible* SVG path
+ * `d` strings morph vertex-by-vertex (the Lottie-style shape tween), anything
+ * else switches discretely.
  */
 export declare function lerpValue(from: PropValue, to: PropValue, u: number): PropValue;
 export {};

package/dist/types/rig.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Character rig: a first-class, declarative skeleton that COMPILES to plain IR.
+ * The character analog of `devicePreset` (generates a NodeIR subtree) and
+ * `motionPreset` (motion vocabulary). A `Bone` tree → nested `group` joints with
+ * stable ids, each holding the bone's vector art; posing is forward-kinematics
+ * (tween a joint group's `rotation`). Because it lowers to groups + paths, it
+ * inherits the renderer, evaluate, overlay editing, preview, validation and the
+ * determinism/golden contract for free — purely additive.
+ *
+ *   const body = humanoid({ id: "hero" });          // one-call skeleton
+ *   poseTo("hero", { armUpperR: -150 }, { duration: 0.4 });   // wave
+ *
+ * Bone convention: the joint sits at the group origin (0,0); the bone extends
+ * along +Y at rotation 0. A child joint's `at` pivot is in the PARENT bone's
+ * local space (e.g. an elbow at [0, upperLength]). Joint names are the STABLE
+ * regen addresses — id `${id}-${name}`; never rename them across a regen. Each
+ * rig instance needs a distinct `id` (duplicate joints collide via the scene's
+ * duplicate-id validation, exactly like `devicePreset`).
+ */
+import type { Ease, NodeIR, TimelineIR } from "./ir.js";
+export interface Bone {
+    /** Stable joint name → group id `${id}-${name}`. */
+    name: string;
+    /** Joint pivot, in the PARENT bone's local space (root: usually [0,0]). */
+    at: [number, number];
+    /** Bone length along +Y — drives the default capsule shape and IK. */
+    length?: number;
+    /** Default-capsule width (default 20). */
+    width?: number;
+    /** Rest-pose angle (deg); 0 = points down (+Y). */
+    rotation?: number;
+    /** Custom bone art (joint at origin, extends +Y) — overrides the default capsule. */
+    shape?: NodeIR[];
+    children?: Bone[];
+}
+export interface RigOpts {
+    /** Id PREFIX for the outer group and every joint (default "rig"); unique per instance. */
+    id?: string;
+    /** Root placement (default 0,0). */
+    x?: number;
+    y?: number;
+    /** Uniform scale (default 1). */
+    scale?: number;
+    /** Outer-group opacity (default 1) — start hidden for an entrance. */
+    opacity?: number;
+    /** Bone line colour (default warm). */
+    color?: string;
+    /** Bone fill (default near-bg, so overlapping joints occlude cleanly). */
+    fill?: string;
+    /** Glow accent for the double-path look on default bones (default off). */
+    glow?: string | false;
+}
+/** jointName → angle (deg). */
+export type Pose = Record<string, number>;
+/** A 4-cubic oval (morphable) centred at (cx,cy). Handy for heads/torsos/hands. */
+export declare function ovalPath(a: number, b: number, cx?: number, cy?: number): string;
+/** Compile a skeleton to a NodeIR group tree. Outer group id = `${id}`; each
+ * joint = `${id}-${name}` (the stable pose/overlay address). */
+export declare function rig(root: Bone, opts?: RigOpts): NodeIR;
+/** A pose as a `states` fragment: `{ "${id}-${joint}": { rotation } }`. Merge
+ * into scene `states` and transition with the existing `to(state, …)`. */
+export declare function rigPose(id: string, pose: Pose): Record<string, {
+    rotation: number;
+}>;
+/** Pose-to-pose on the timeline: a `par` (or `stagger`) of rotation tweens. */
+export declare function poseTo(id: string, pose: Pose, opts?: {
+    duration?: number;
+    ease?: Ease;
+    stagger?: number;
+}): TimelineIR;
+/**
+ * 2-bone inverse kinematics. Returns `[shoulderDeg, elbowDeg]` (the +Y-down bone
+ * convention) that place the chain's tip at `(dx,dy)` relative to the root joint.
+ * Exact for in-reach targets; clamps gracefully (no NaN) when out of reach.
+ * `flip` chooses the elbow-up vs elbow-down solution.
+ *
+ * Derivation: with R(θ) the canvas rotation, the tip is
+ * R(θ1)·[ (0,upper) + R(θ2)·(0,lower) ]. The bracket has length D=hypot(dx,dy),
+ * giving cosθ2 = (D²−u²−l²)/(2ul); then θ1 rotates that bracket onto the target.
+ */
+export declare function ikReach(upper: number, lower: number, dx: number, dy: number, flip?: boolean): [number, number];
+export interface HumanoidOpts extends Omit<RigOpts, never> {
+}
+/** A ready upright humanoid skeleton — the one-call body. Joints:
+ * chest, head, armUpper/LowerL, armUpper/LowerR, legUpper/LowerL, legUpper/LowerR.
+ * Rooted at the chest so every limb extends naturally along +Y. */
+export declare function humanoid(opts?: HumanoidOpts): NodeIR;

package/guides/edsl-guide.md

@@ -41,6 +41,12 @@ Factories return plain data. Every node needs a unique `id`.
   the art's centre (e.g. the viewBox centre) so `scale`/`rotation` happen about the
   middle. `d` is drawn in its own coords; `x`/`y` place that pivot. Classic logo
   reveal: a stroke path drawing on, then a fill path fading in over it.
+  **`d` is animatable (shape morph):** `tween(id, { d: otherShape }, …)` morphs
+  the path vertex-by-vertex (the Lottie-style shape tween) when both `d` strings
+  share the same command sequence and arg counts — author the two poses with the
+  same structure (e.g. both 4-cubic ovals). Arcs (`A`) can't morph (their 0/1
+  flags aren't interpolable) and incompatible shapes snap at the midpoint; build
+  morph targets from `M/L/C/Q/Z` only.
 - `image({ id, src, x, y, width, height, opacity?, rotation?, scale?, anchor? })` —
   `src` is a file path, absolute or relative to the scene file; drawn stretched
   to `width`×`height` (png/jpg/webp). `src` switches discretely (no crossfade) —
@@ -115,6 +121,52 @@ bound — e.g. a pulse only during the hold:
 `oscillate("title", "scale", { amplitude: 0.04, frequency: 1.2 }, { from: 1.5, until: 3.5 })`.
 Omit the window to run for the whole scene.
 
+## Character rig (skeleton, poses, IK)
+
+A first-class, declarative character rig that **compiles to plain IR** (nested
+`group` joints + bone paths) — the character analog of `devicePreset`. It needs
+no new renderer concept, so overlays/preview/determinism all apply.
+
+- `humanoid({ id, x, y, scale, opacity?, color?, fill?, glow? })` → a NodeIR: a
+  ready upright body. Joints (stable ids `${id}-${name}`): `chest`, `head`,
+  `armUpperL/armLowerL`, `armUpperR/armLowerR`, `legUpperL/legLowerL`,
+  `legUpperR/legLowerR`. Drop it in `nodes`.
+- `rig(boneTree, opts)` → build your own skeleton. A `Bone` is
+  `{ name, at:[x,y], length?, width?, rotation?, shape?, children? }`. The joint
+  sits at the group origin; the bone extends **+Y at rotation 0**; a child's `at`
+  pivot is in the PARENT bone's local space (e.g. an elbow at `[0, upperLength]`).
+  Nested groups give forward kinematics — a child's rotation composes on its
+  parent's. Default bone = a bezier capsule (morphable); pass `shape` for custom art.
+- A **pose** is `{ jointName: angleDeg }` (0 = bone points down). Animate it:
+  - `poseTo(id, pose, { duration, ease, stagger? })` → a timeline step (a `par`
+    of rotation tweens). Sequence poses for wave/jump/run.
+  - `rigPose(id, pose)` → a `states` fragment, to transition with `to(state, …)`.
+- `ikReach(upper, lower, dx, dy, flip?)` → `[shoulderDeg, elbowDeg]` that place a
+  2-bone limb's tip at `(dx,dy)` relative to its shoulder joint (law of cosines;
+  clamps when out of reach). Feed the two angles into a pose.
+- Joint names are the **stable regen addresses** — never rename them across a
+  regen; each rig instance needs a distinct `id` (duplicates collide via scene
+  validation). Squash/stretch and expressions are per-bone `d` morphs (above),
+  composed on top of FK posing. Idle sway/breathing = `oscillate` on a joint.
+- `figure(opts)` — a **dressed** character (the styled sibling of `humanoid`):
+  same skeleton, but coloured flat-design shapes. `style: "clean"` (corporate-flat
+  / undraw register, the default) or `"cute"` (mascot); `palette` knobs
+  (`skin`/`hair`/`top`/`pants`/`shoe`/`accent`) re-skin it — for `clean` the top
+  follows `accent`, so `figure({ palette: { accent: "#3B82F6" } })` recolours the
+  whole figure; `face: false` makes it faceless. It exposes the humanoid joint
+  ids, so `characterPreset` / `ikReach` drive it unchanged. Use it as the
+  supporting actor in a product promo (gesturing at a `devicePreset`), not the hero.
+- `characterPreset(name, opts)` — a **seeded motion generator** for a `humanoid`
+  or `figure` rig (the character analog of `motionPreset`). Returns a composable `beat`;
+  drop it in the timeline: `seq(characterPreset("walk", { target: "hero", at:
+  [cx, cy], cycles: 4 }))`. Names: `walk`, `run`, `jump`, `dance`, `wave`,
+  `cheer`. Knobs: `target` (rig id), `energy` 0..1, `speed` (>0, divides
+  durations), `seed` (varies within the family), `cycles` (walk/run/dance),
+  `facing` (±1), `at: [x,y]` (the rig's scene position — needed for walk travel
+  & jump lift), `travel` (px/cycle, 0 = in place), `label` (unique beat name —
+  set it when the same preset is used more than once in a scene). Legs use
+  `ikReach`, arms FK; pure keyframes, so add continuous idle yourself with `oscillate`.
+
 ## Audio (optional)
 
 Label-anchored sound design — cues follow retiming and regeneration:

package/guides/regen-contract.md

@@ -16,3 +16,14 @@ source):
 When the contract is broken anyway, `composeScene` skips the affected edits
 and reports them as orphans with the known-ids list — loud, diagnosable,
 never a silent drop and never a render failure.
+
+## Generated subtrees (devicePreset, rig/humanoid)
+
+Generators emit nodes with deterministic ids under an instance prefix, and those
+ids are stable addresses too. For `devicePreset(name,{id})` the screen/content
+parts are `${id}-screen` / `${id}-content`. For `rig(...)` / `humanoid({id})`
+each joint is `${id}-${jointName}` (e.g. `hero-armUpperR`) and its bone art is
+`${id}-${jointName}-shape`. Across a regen, **keep the instance `id` and the
+joint `name`s** for any character/device that survives the redesign — overlay
+edits (a retimed wave, a nudged limb angle) reference those exact ids. Renaming a
+joint orphans the edit, exactly like renaming a hand-authored node id.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Declarative motion graphics that AI can write and humans can tweak — human edits survive AI regeneration. Deterministic mp4 renders from a plain-data scene format.",
   "keywords": [
     "motion-graphics",