@ikijs/editor 0.1.0 → 0.2.1

package/README.md

@@ -1,15 +1,15 @@
 # @ikijs/editor
 
-**Headless** editing core for [`.iki`](../format) models — a document with
+**Headless** editing core for [`.iki`](https://github.com/zeikar/iki/tree/main/packages/format) models — a document with
 undo/redo, invertible edit commands, atlas layout + UV math, and the auto-rigger.
 
 This package ships no UI. It is the model and command layer an editor is built
 _on_, not an editor you can mount.
 
 Everything here is pure logic — no DOM, no canvas, no WebGL. It depends only on
-[`@ikijs/format`](../format), so the same core backs this repo's
+[`@ikijs/format`](https://github.com/zeikar/iki/tree/main/packages/format), so the same core backs this repo's
 browser editor app (`examples/editor`), the Node MCP server
-([`@ikijs/mcp`](../mcp)), and tests.
+([`@ikijs/mcp`](https://github.com/zeikar/iki/tree/main/packages/mcp)), and tests.
 
 ## Install
 

package/dist/index.js

@@ -1663,14 +1663,25 @@ function createDefaultWarpDeformer(model) {
 // src/auto-rig.ts
 var import_format3 = require("@ikijs/format");
 var ROLE_TABLE = {
-  // hair_back stays rigid (silhouette behind the face); per-layer front/back
-  // depth parallax is a later slice.
-  hair_back: { deformer: "headDeformer", order: 0, mesh: false },
+  // The silhouette behind the face. It rides the rigid head (not faceWarp,
+  // whose grid it would stretch across the shoulders) as a MESH: it bends on
+  // the turn through its own part warp (bakeHairBackTurnWarp) and swings its
+  // ends on the hair-sway warps.
+  hair_back: { deformer: "headDeformer", order: 0, mesh: true },
+  // The torso. Alone among the roles it hangs from NO deformer: the head turns
+  // about the neck pivot while the shoulders stay put, which is what keeps the
+  // character from reading as a floating head. Drawn over the back hair so long
+  // hair falls behind the shoulders.
+  body: { deformer: "none", order: 5, mesh: false },
   face: { deformer: "faceWarp", order: 10, mesh: true },
   nose: { deformer: "faceWarp", order: 15, mesh: true },
   blush_L: { deformer: "faceWarp", order: 20, mesh: true },
   blush_R: { deformer: "faceWarp", order: 20, mesh: true },
   mouth: { deformer: "faceWarp", order: 25, mesh: true },
+  // An OPTIONAL second mouth drawing, open. When present the two cross-fade on
+  // MouthOpen instead of the closed one being stretched, which is the
+  // difference between a portrait rig and one that can lip-sync.
+  mouth_open: { deformer: "faceWarp", order: 26, mesh: true },
   eye_L: { deformer: "faceWarp", order: 30, mesh: true, eyeSide: "L" },
   eye_R: { deformer: "faceWarp", order: 30, mesh: true, eyeSide: "R" },
   iris_L: { deformer: "faceWarp", order: 31, mesh: true, eyeSide: "L" },
@@ -1822,29 +1833,62 @@ function createPixelGridMesh(cols, rows, w, h) {
   }
   return { vertices, uvs, indices };
 }
-function bakeHeadTurnGridWarpCentered(grid, parameter, centerX) {
-  const ANGLES = [-30, 0, 30];
-  const halfWidth = (grid.points[grid.cols * 2] - grid.points[0]) / 2;
-  const RADIUS = halfWidth * (0.6 / 0.5);
+var HEAD_CYLINDER_RADIUS_FACTOR = 0.6 / 0.5;
+var HEAD_TURN_MAX_DEG = 30;
+function headTurnParallaxUnit(gridHalfWidth) {
+  return gridHalfWidth * HEAD_CYLINDER_RADIUS_FACTOR * Math.sin(HEAD_TURN_MAX_DEG * (Math.PI / 180));
+}
+function gridReach(grid, axis, center) {
+  let reach = 0;
+  for (let i = axis; i < grid.points.length; i += 2) {
+    reach = Math.max(reach, Math.abs(grid.points[i] - center));
+  }
+  return reach;
+}
+function pinnedCylinderBend(local, radius, theta) {
+  const alpha = Math.asin(Math.max(-1, Math.min(1, local / radius)));
+  return radius * Math.sin(alpha + theta) - local - radius * Math.sin(theta);
+}
+function bakeHeadTurnGridWarp2DCentered(grid, parameterX, parameterY, centerX, centerY) {
+  const STOPS = [-HEAD_TURN_MAX_DEG, 0, HEAD_TURN_MAX_DEG];
+  const RADIUS_X = gridReach(grid, 0, centerX) * HEAD_CYLINDER_RADIUS_FACTOR;
+  const RADIUS_Y = gridReach(grid, 1, centerY) * HEAD_CYLINDER_RADIUS_FACTOR;
   const pointCount = grid.points.length / 2;
   const DEG_TO_RAD = Math.PI / 180;
-  const keyforms = ANGLES.map((angleDeg) => {
-    const theta = angleDeg * DEG_TO_RAD;
-    const offsets = [];
-    for (let i = 0; i < pointCount; i++) {
-      const x = grid.points[i * 2];
-      const localX = x - centerX;
-      const alpha = Math.asin(Math.max(-1, Math.min(1, localX / RADIUS)));
-      const xPrime = centerX + RADIUS * Math.sin(alpha + theta);
-      const dx = xPrime - x;
-      offsets.push(dx, 0);
-    }
-    return { value: angleDeg, offsets };
-  });
-  return { parameter, keyforms };
+  const keyforms2d = [];
+  for (const angleY of STOPS) {
+    const thetaY = angleY * NOD_BEND * DEG_TO_RAD;
+    for (const angleX of STOPS) {
+      const thetaX = angleX * DEG_TO_RAD;
+      const offsets = [];
+      for (let i = 0; i < pointCount; i++) {
+        offsets.push(
+          pinnedCylinderBend(grid.points[i * 2] - centerX, RADIUS_X, thetaX),
+          pinnedCylinderBend(
+            grid.points[i * 2 + 1] - centerY,
+            RADIUS_Y,
+            thetaY
+          )
+        );
+      }
+      keyforms2d.push({ offsets });
+    }
+  }
+  return {
+    parameter: parameterX,
+    parameterY,
+    valuesX: STOPS,
+    valuesY: STOPS,
+    keyforms2d
+  };
 }
 var EYE_STACK_PREFIXES = ["eye_", "iris_", "pupil_", "highlight_"];
-function bindingsForRole(spec, role, cropW, cropH) {
+var HAIR_FRONT_DEPTH = 0.1;
+var HAIR_BACK_DEPTH = -0.08;
+var NOD_TRAVEL = 30;
+var NOD_BEND = 0.5;
+var HAIR_BACK_NOD_DEPTH = -0.07;
+function bindingsForRole(spec, role, cropW, cropH, options = {}) {
   const isEyeStack = EYE_STACK_PREFIXES.some((p) => role.startsWith(p));
   if (isEyeStack && spec.eyeSide !== void 0) {
     const isGazeRole = role.startsWith("iris_") || role.startsWith("pupil_") || role.startsWith("highlight_");
@@ -1866,22 +1910,47 @@ function bindingsForRole(spec, role, cropW, cropH) {
       }
     ];
   }
+  const mouthForm = {
+    // Mouth form: scaleX from -0.2 (pursed, param=-1) to 0.4 (wide, param=1).
+    parameter: import_format3.StandardParameter.MouthForm,
+    channel: "scaleX",
+    from: -0.2,
+    to: 0.4
+  };
   if (role === "mouth") {
+    if (options.hasMouthOpen) {
+      return [
+        {
+          parameter: import_format3.StandardParameter.MouthOpen,
+          channel: "opacity",
+          from: 1,
+          to: 0
+        },
+        mouthForm
+      ];
+    }
     return [
       // Mouth open: scaleY from 0 (closed, param=0) to 3 (wide open, param=1).
+      // Only a fallback — it distorts, but it is better than a mouth that
+      // cannot open at all when the layer set has no open drawing.
       {
         parameter: import_format3.StandardParameter.MouthOpen,
         channel: "scaleY",
         from: 0,
         to: 3
       },
-      // Mouth form: scaleX from -0.2 (pursed, param=-1) to 0.4 (wide, param=1).
+      mouthForm
+    ];
+  }
+  if (role === "mouth_open") {
+    return [
       {
-        parameter: import_format3.StandardParameter.MouthForm,
-        channel: "scaleX",
-        from: -0.2,
-        to: 0.4
-      }
+        parameter: import_format3.StandardParameter.MouthOpen,
+        channel: "opacity",
+        from: 0,
+        to: 1
+      },
+      mouthForm
     ];
   }
   if (role === "brow_L" || role === "brow_R") {
@@ -1919,21 +1988,29 @@ function bindingsForRole(spec, role, cropW, cropH) {
       ];
     }
   }
-  if (role === "hair_front") {
-    return [
-      {
-        parameter: import_format3.StandardParameter.HairSwayX,
-        channel: "rotate",
-        from: -8,
-        to: 8
-      },
-      {
-        parameter: import_format3.StandardParameter.HairSwayX,
+  if (role === "hair_front" || role === "hair_back") {
+    const isFront = role === "hair_front";
+    const depth = isFront ? HAIR_FRONT_DEPTH : HAIR_BACK_DEPTH;
+    const parallax = [];
+    const shiftX = depth * (options.parallaxUnit ?? 0);
+    if (shiftX !== 0) {
+      parallax.push({
+        parameter: import_format3.StandardParameter.AngleX,
         channel: "translateX",
-        from: -10,
-        to: 10
-      }
-    ];
+        from: -shiftX,
+        to: shiftX
+      });
+    }
+    const shiftY = (isFront ? 0 : HAIR_BACK_NOD_DEPTH) * (options.parallaxUnitY ?? 0);
+    if (shiftY !== 0) {
+      parallax.push({
+        parameter: import_format3.StandardParameter.AngleY,
+        channel: "translateY",
+        from: -shiftY,
+        to: shiftY
+      });
+    }
+    return parallax;
   }
   return [];
 }
@@ -1956,9 +2033,62 @@ function bakeEyelidFoldWarp(mesh, parameter, creaseOffsetY, k) {
     ]
   };
 }
+var HAIR_BACK_BEND_RADIUS_FACTOR = 2.5;
+var HAIR_BACK_FAR_BULGE = 0.22;
+function bakeHairBackTurnWarp(mesh, parameter) {
+  let left = Infinity;
+  let right = -Infinity;
+  for (let i = 0; i < mesh.vertices.length; i += 2) {
+    left = Math.min(left, mesh.vertices[i]);
+    right = Math.max(right, mesh.vertices[i]);
+  }
+  const halfWidth = (right - left) / 2;
+  const radius = halfWidth * HAIR_BACK_BEND_RADIUS_FACTOR;
+  const bulge = HAIR_BACK_FAR_BULGE * halfWidth;
+  const DEG_TO_RAD = Math.PI / 180;
+  const keyforms = [-HEAD_TURN_MAX_DEG, 0, HEAD_TURN_MAX_DEG].map((deg) => {
+    const theta = deg * DEG_TO_RAD;
+    const s = Math.sign(deg);
+    const offsets = [];
+    for (let i = 0; i < mesh.vertices.length; i += 2) {
+      const x = mesh.vertices[i];
+      const far = Math.max(0, -s * x / halfWidth);
+      offsets.push(pinnedCylinderBend(x, radius, theta) - s * bulge * far, 0);
+    }
+    return { value: deg, offsets };
+  });
+  return { parameter, keyforms };
+}
+var HAIR_SWAY_TIP_FRACTION = 0.09;
+var HAIR_SWAY_CURL = 1.5;
+var HAIR_SWAY_RANGE = 20;
+var HAIR_SWAY_PEAK_FRACTION = 0.56;
+function bakeHairSwayWarp(mesh, parameter, tipShift, range) {
+  let top = -Infinity;
+  let bottom = Infinity;
+  for (let i = 1; i < mesh.vertices.length; i += 2) {
+    top = Math.max(top, mesh.vertices[i]);
+    bottom = Math.min(bottom, mesh.vertices[i]);
+  }
+  const height = top - bottom;
+  const swing = [];
+  for (let i = 0; i < mesh.vertices.length; i += 2) {
+    const u = height > 0 ? (top - mesh.vertices[i + 1]) / height : 0;
+    swing.push(tipShift * Math.pow(u, HAIR_SWAY_CURL), 0);
+  }
+  return {
+    parameter,
+    keyforms: [
+      // `0 - v`, not `-v`: the pinned root row must stay a plain +0.
+      { value: -range, offsets: swing.map((v) => 0 - v) },
+      { value: range, offsets: swing }
+    ]
+  };
+}
 function generateIkiFromLayerSet(layers, canvas) {
   validateLayerInputs(layers, canvas);
   const hasHair = layers.some((l) => l.role === "hair_front");
+  const hasMouthOpen = layers.some((l) => l.role === "mouth_open");
   const parameters = [
     {
       id: import_format3.StandardParameter.MouthOpen,
@@ -2009,6 +2139,20 @@ function generateIkiFromLayerSet(layers, canvas) {
       max: 30,
       default: 0
     },
+    {
+      id: import_format3.StandardParameter.AngleY,
+      name: "Head Angle Y",
+      min: -30,
+      max: 30,
+      default: 0
+    },
+    {
+      id: import_format3.StandardParameter.AngleZ,
+      name: "Head Angle Z",
+      min: -30,
+      max: 30,
+      default: 0
+    },
     {
       id: import_format3.StandardParameter.Breath,
       name: "Breath",
@@ -2046,13 +2190,22 @@ function generateIkiFromLayerSet(layers, canvas) {
     }
   ];
   if (hasHair) {
-    parameters.push({
-      id: import_format3.StandardParameter.HairSwayX,
-      name: "Hair Sway X",
-      min: -20,
-      max: 20,
-      default: 0
-    });
+    parameters.push(
+      {
+        id: import_format3.StandardParameter.HairSwayX,
+        name: "Hair Sway X",
+        min: -HAIR_SWAY_RANGE,
+        max: HAIR_SWAY_RANGE,
+        default: 0
+      },
+      {
+        id: import_format3.StandardParameter.HairSwayZ,
+        name: "Hair Sway Z",
+        min: -HAIR_SWAY_RANGE,
+        max: HAIR_SWAY_RANGE,
+        default: 0
+      }
+    );
   }
   const faceLayers = layers.filter((l) => l.role === "face");
   const faceLayer = faceLayers[0];
@@ -2110,16 +2263,22 @@ function generateIkiFromLayerSet(layers, canvas) {
       unionMaxY
     )
   };
+  const faceCenterY = faceTransform.y;
+  const halfH = Math.max(faceCenterY - unionMinY, unionMaxY - faceCenterY);
+  const parallaxUnit = headTurnParallaxUnit(halfW);
+  const parallaxUnitY = headTurnParallaxUnit(halfH);
   const faceBottom = faceTransform.y - faceCropH / 2;
   const neckPivot = {
     x: faceCenterX,
     y: faceBottom - faceCropH * 0.15
     // 15% below face bottom = neck
   };
-  const faceWarpBake = bakeHeadTurnGridWarpCentered(
+  const faceWarp2d = bakeHeadTurnGridWarp2DCentered(
     faceGrid,
     import_format3.StandardParameter.AngleX,
-    faceCenterX
+    import_format3.StandardParameter.AngleY,
+    faceCenterX,
+    faceCenterY
   );
   const deformers = [
     // headDeformer: rigid matrix rotating/translating the whole head about the
@@ -2140,6 +2299,27 @@ function generateIkiFromLayerSet(layers, canvas) {
           from: -50,
           to: 50
         },
+        // Nod: a vertical translate only. No rotate — a pitch expressed as a
+        // rigid rotation would sum with the roll below at diagonal poses,
+        // collapsing pitch into roll.
+        {
+          parameter: import_format3.StandardParameter.AngleY,
+          channel: "translateY",
+          from: -NOD_TRAVEL,
+          to: NOD_TRAVEL
+        },
+        // Tilt: the whole head rolls about the neck pivot, one degree per
+        // degree. Positive AngleZ is clockwise on screen (engine rotate is
+        // CCW-positive, hence the flipped from/to) — Live2D's convention, and
+        // the same sense as the lean above: in Live2D's own sample motions
+        // AngleZ carries the sign of AngleX 214 times out of 222. The two
+        // rotations sum, which is correct for two rolls about one pivot.
+        {
+          parameter: import_format3.StandardParameter.AngleZ,
+          channel: "rotate",
+          from: 30,
+          to: -30
+        },
         {
           parameter: import_format3.StandardParameter.Breath,
           channel: "translateY",
@@ -2150,12 +2330,14 @@ function generateIkiFromLayerSet(layers, canvas) {
     },
     // faceWarp: cylinder-bend warp parented to headDeformer; grid is symmetric
     // about faceCenterX so the bake's cylinder axis aligns with the face center.
+    // One 2D warp carries both the turn and the nod (a deformer holds either
+    // `warps` or `warp2d`, never both).
     {
       kind: "warp",
       id: "faceWarp",
       parent: "headDeformer",
       grid: faceGrid,
-      warps: [faceWarpBake]
+      warp2d: faceWarp2d
     }
   ];
   const eyeCreaseBySide = {};
@@ -2175,7 +2357,12 @@ function generateIkiFromLayerSet(layers, canvas) {
     const { role, bbox, cropW, cropH, canvasW, canvasH } = layer;
     const spec = ROLE_TABLE[role];
     const t = bboxToTransform(bbox, canvasW, canvasH, role);
-    const roleBindings = bindingsForRole(spec, role, cropW, cropH);
+    const roleBindings = bindingsForRole(spec, role, cropW, cropH, {
+      hasMouthOpen,
+      parallaxUnit,
+      parallaxUnitY
+    });
+    const deformerId = spec.deformer === "none" ? void 0 : spec.deformer;
     if (spec.mesh) {
       const mesh = createPixelGridMesh(4, 4, cropW, cropH);
       const part = {
@@ -2185,23 +2372,58 @@ function generateIkiFromLayerSet(layers, canvas) {
         height: 1,
         order: spec.order,
         transform: t,
-        deformer: spec.deformer,
+        deformer: deformerId,
         mesh
       };
       if (roleBindings.length > 0) {
         part.bindings = roleBindings;
       }
+      if ((role === "hair_front" || role === "hair_back") && hasHair) {
+        let tipShift = HAIR_SWAY_TIP_FRACTION * cropH;
+        if (role === "hair_front") {
+          const shift = HAIR_FRONT_DEPTH * parallaxUnit;
+          const headroom = Math.min(
+            faceGridMaxX - (t.x + cropW / 2),
+            t.x - cropW / 2 - faceGridMinX
+          ) - shift;
+          tipShift = Math.min(
+            tipShift,
+            Math.max(0, headroom) / HAIR_SWAY_PEAK_FRACTION
+          );
+        }
+        part.warps = [
+          bakeHairSwayWarp(
+            mesh,
+            import_format3.StandardParameter.HairSwayX,
+            tipShift,
+            HAIR_SWAY_RANGE
+          ),
+          bakeHairSwayWarp(
+            mesh,
+            import_format3.StandardParameter.HairSwayZ,
+            tipShift,
+            HAIR_SWAY_RANGE
+          )
+        ];
+      }
+      if (role === "hair_back") {
+        part.warps = [
+          ...part.warps ?? [],
+          bakeHairBackTurnWarp(mesh, import_format3.StandardParameter.AngleX)
+        ];
+      }
       if (spec.eyeSide !== void 0) {
         const isLash = role.startsWith("lash_");
         if (role.startsWith("eye_") || isLash) {
           const openParam = spec.eyeSide === "L" ? import_format3.StandardParameter.EyeOpenLeft : import_format3.StandardParameter.EyeOpenRight;
           const creaseWorldY = eyeCreaseBySide[spec.eyeSide] ?? t.y - EYELID_FOLD_CREASE * cropH;
+          const hasLash = layers.some((l) => l.role === `lash_${spec.eyeSide}`);
           part.warps = [
             bakeEyelidFoldWarp(
               mesh,
               openParam,
               creaseWorldY - t.y,
-              isLash ? LASH_FOLD_K : EYELID_FOLD_K
+              isLash ? LASH_FOLD_K : hasLash ? 0 : EYELID_FOLD_K
             )
           ];
         } else {
@@ -2210,15 +2432,19 @@ function generateIkiFromLayerSet(layers, canvas) {
       }
       return part;
     } else {
-      return {
+      const part = {
         id: role,
         color: [1, 1, 1, 1],
         width: cropW,
         height: cropH,
         order: spec.order,
         transform: t,
-        deformer: spec.deformer
+        deformer: deformerId
       };
+      if (roleBindings.length > 0) {
+        part.bindings = roleBindings;
+      }
+      return part;
     }
   });
   const model = {
@@ -2229,9 +2455,12 @@ function generateIkiFromLayerSet(layers, canvas) {
     parameters,
     deformers,
     parts,
-    // Secondary motion: a spring lags AngleX onto HairSwayX so front hair sways
-    // behind the head turn (same constants as the hand-authored sample). Omitted
-    // when there is no front hair to drive.
+    // Secondary motion: one spring lags AngleX onto HairSwayX so front hair
+    // sways behind the head turn (same constants as the hand-authored sample),
+    // and a second lags AngleZ onto HairSwayZ so it swings behind a tilt. Two
+    // rigs because a rig has one input and one output (validator-enforced).
+    // Both hair parts read the outputs through root-pinned sway warps.
+    // Omitted when there is no front hair to drive.
     physics: hasHair ? [
       {
         id: "hairSway",
@@ -2240,6 +2469,14 @@ function generateIkiFromLayerSet(layers, canvas) {
         mass: 1,
         stiffness: 80,
         damping: 10
+      },
+      {
+        id: "hairTilt",
+        input: { parameter: import_format3.StandardParameter.AngleZ, weight: 1 },
+        output: { parameter: import_format3.StandardParameter.HairSwayZ, scale: -10 },
+        mass: 1,
+        stiffness: 80,
+        damping: 10
       }
     ] : void 0
   };