@ikijs/editor 0.29.0 → 0.30.0

package/dist/index.js

@@ -1652,6 +1652,8 @@ var ROW_RUN_ROLES = /* @__PURE__ */ new Set([
   "face",
   "hair_front",
   "hair_back",
+  "hair_side_L",
+  "hair_side_R",
   "body",
   "arm_L",
   "arm_R",
@@ -2081,8 +2083,9 @@ function deriveProfile(v) {
     /** The mouth's far corner rises (its near end drops) by this much: it
      *  stays level. */
     mouthTiltDeg: 0,
-    /** The front hair (bangs and side locks) rides the face at this share of
-     *  its translation. */
+    /** The front hair (its bangs and its own side strands; a `hair_side_*` lock
+     *  takes it only down to its root, `hairSideField`) rides the face at this
+     *  share of its translation. */
     hairFollow: v.hairFollow,
     /** The head's outline at the eye row holds: where the front hair draws
      *  it, its outer edge follows the face this much on a row where no back
@@ -2298,177 +2301,15 @@ function meshPoints(mesh, box) {
   return out;
 }
 
-// src/auto-rig/roles.ts
-var import_format3 = require("@ikijs/format");
-var LIP_ROLES = ["mouth_inner", "lip_lower", "lip_upper"];
-var isLipRole = (role) => LIP_ROLES.includes(role);
-var LIP_INSIDE_ROLES = ["mouth_tongue", "mouth_teeth"];
-var isLipInsideRole = (role) => LIP_INSIDE_ROLES.includes(role);
-var SHUT_BY = new Map([
-  ["eye_L", import_format3.StandardParameter.EyeOpenLeft],
-  ["lash_lower_L", import_format3.StandardParameter.EyeOpenLeft],
-  ["eye_R", import_format3.StandardParameter.EyeOpenRight],
-  ["lash_lower_R", import_format3.StandardParameter.EyeOpenRight],
-  ...[...LIP_ROLES, ...LIP_INSIDE_ROLES].map((id) => [
-    id,
-    import_format3.StandardParameter.MouthOpen
-  ])
-]);
-var ROLE_TABLE = [
-  { role: "hair_back", family: "hair_back" },
-  { role: "body", family: "body" },
-  { role: "arm_L", family: "arm", parts: ["elbow_L", "forearm_L", "arm_L"] },
-  { role: "arm_R", family: "arm", parts: ["elbow_R", "forearm_R", "arm_R"] },
-  { role: "face", family: "face", required: true },
-  { role: "blush_L", family: "face" },
-  { role: "blush_R", family: "face" },
-  { role: "nose", family: "nose" },
-  { role: "mouth", family: "mouth" },
-  { role: "mouth_open", family: "mouth" },
-  // The lip set, back to front: the interior, the tongue and the teeth clipped
-  // to it, the lower lip's skin, the upper lip and its line over both. It
-  // folds open instead of crossfading (`mouth.ts`), so it stands in for
-  // `mouth`, never beside it.
-  { role: "mouth_inner", family: "mouth" },
-  { role: "mouth_tongue", family: "mouth" },
-  { role: "mouth_teeth", family: "mouth" },
-  { role: "lip_lower", family: "mouth" },
-  { role: "lip_upper", family: "mouth" },
-  { role: "eye_L", family: "eye_L", required: true },
-  { role: "eye_R", family: "eye_R", required: true },
-  { role: "iris_L", family: "eye_L" },
-  { role: "iris_R", family: "eye_R" },
-  { role: "pupil_L", family: "eye_L" },
-  { role: "pupil_R", family: "eye_R" },
-  { role: "highlight_L", family: "eye_L" },
-  { role: "highlight_R", family: "eye_R" },
-  { role: "lash_lower_L", family: "eye_L" },
-  { role: "lash_lower_R", family: "eye_R" },
-  { role: "lash_L", family: "eye_L" },
-  { role: "lash_R", family: "eye_R" },
-  { role: "brow_L", family: "brow_L" },
-  { role: "brow_R", family: "brow_R" },
-  { role: "hair_front", family: "hair_front" },
-  // Drawn above the face and the hair: a raised hand passes them.
-  { role: "forearm_pose_L", family: "forearm_pose" },
-  { role: "forearm_pose_R", family: "forearm_pose" }
-];
-var REQUIRED_ROLES = ROLE_TABLE.filter(
-  (r) => r.required
-).map((r) => r.role);
-var SPEC_BY_ROLE = new Map(ROLE_TABLE.map((r, i) => [r.role, { ...r, i }]));
-function roleSpec(role) {
-  const spec = SPEC_BY_ROLE.get(role);
-  if (spec === void 0) throw new Error(`auto-rig: unknown role "${role}"`);
-  return spec;
-}
-function partIdsOfRole(role) {
-  return roleSpec(role).parts ?? [role];
-}
-var ROLE_BY_PART = new Map(
-  ROLE_TABLE.flatMap((r) => (r.parts ?? []).map((p) => [p, r.role]))
-);
-function roleOfPart(partId) {
-  return ROLE_BY_PART.get(partId) ?? partId;
-}
-var ALIASES = {
-  eyebrow_L: "brow_L",
-  eyebrow_R: "brow_R",
-  eye_white_L: "eye_L",
-  eye_white_R: "eye_R"
-};
-function roleOf(fileName) {
-  const role = fileName.replace(/\.[^.]+$/, "").toLowerCase().replace(/[-\s]+/g, "_").replace(/_([lr])$/, (_, s) => `_${s.toUpperCase()}`);
-  return ALIASES[role] ?? role;
-}
-function checkArmsHaveBody(roles) {
-  const has = new Set(roles);
-  if (has.has("body")) return;
-  const arm = ROLE_TABLE.find((r) => r.family === "arm" && has.has(r.role));
-  if (arm !== void 0) {
-    throw new Error(
-      `auto-rig: ${arm.role} needs a body layer (an arm hangs from the body's shoulder)`
-    );
-  }
-}
-function checkMouth(roles) {
-  const has = new Set(roles);
-  const present = LIP_ROLES.filter((r) => has.has(r));
-  const inside = LIP_INSIDE_ROLES.filter((r) => has.has(r));
-  if (inside.length > 0 && present.length === 0) {
-    throw new Error(
-      `auto-rig: ${inside[0]} needs the lip set ${LIP_ROLES.join(", ")} (it is cut from the interior and clipped to it)`
-    );
-  }
-  if (present.length === 0) {
-    if (!has.has("mouth")) {
-      throw new Error(
-        `auto-rig: missing required role mouth (or the lip set ${LIP_ROLES.join(", ")})`
-      );
-    }
-    return;
-  }
-  if (present.length < LIP_ROLES.length) {
-    throw new Error(
-      `auto-rig: the lip set is partial: missing ${LIP_ROLES.filter((r) => !has.has(r)).join(", ")}`
-    );
-  }
-  const mixed = ["mouth", "mouth_open"].filter((r) => has.has(r));
-  if (mixed.length > 0) {
-    throw new Error(
-      `auto-rig: the lip set cannot be mixed with ${mixed.join(", ")} (the lip set replaces the mouth drawings; use one or the other)`
-    );
-  }
-}
-function checkPosesHaveArms(roles) {
-  const has = new Set(roles);
-  for (const side of ["L", "R"]) {
-    if (has.has(`forearm_pose_${side}`) && !has.has(`arm_${side}`)) {
-      throw new Error(
-        `auto-rig: forearm_pose_${side} needs an arm_${side} layer (a pose forearm hangs from its arm's elbow)`
-      );
-    }
-  }
-}
-function parseLayerRoles(fileNames) {
-  const seen = /* @__PURE__ */ new Map();
-  const out = [];
-  for (const fileName of fileNames) {
-    const role = roleOf(fileName);
-    if (!SPEC_BY_ROLE.has(role)) {
-      throw new Error(
-        `auto-rig: "${fileName}" names no known role (expected one of ${ROLE_TABLE.map((r) => r.role).join(", ")})`
-      );
-    }
-    const prior = seen.get(role);
-    if (prior !== void 0) {
-      throw new Error(
-        `auto-rig: role "${role}" is named twice ("${prior}" and "${fileName}")`
-      );
-    }
-    seen.set(role, fileName);
-    out.push({ role, fileName });
-  }
-  const missing = REQUIRED_ROLES.filter((r) => !seen.has(r));
-  if (missing.length > 0) {
-    throw new Error(
-      `auto-rig: missing required role${missing.length > 1 ? "s" : ""} ${missing.join(", ")}`
-    );
-  }
-  checkMouth(seen.keys());
-  checkArmsHaveBody(seen.keys());
-  checkPosesHaveArms(seen.keys());
-  return out;
-}
-
 // src/auto-rig/mouth.ts
 var import_format5 = require("@ikijs/format");
 
 // src/auto-rig/drivers.ts
-var import_format4 = require("@ikijs/format");
+var import_format3 = require("@ikijs/format");
 var SWAY_RANGE = 20;
 var SWAY_CURVE = 1.4;
 var HAIR_HANG = 0.35;
+var LOCK_HANG_SPAN = 1;
 var Z_STOPS = [-30, 0, 30];
 function localWarp(parameter, mesh, box, values, f) {
   const pts = meshPoints(mesh, box);
@@ -2543,13 +2384,13 @@ function gazeBindings(irisW, share = 1) {
   const gy = AMPLITUDE.gazeY * irisW * share;
   return [
     {
-      parameter: import_format4.StandardParameter.EyeballX,
+      parameter: import_format3.StandardParameter.EyeballX,
       channel: "translateX",
       from: -round1(gx),
       to: round1(gx)
     },
     {
-      parameter: import_format4.StandardParameter.EyeballY,
+      parameter: import_format3.StandardParameter.EyeballY,
       channel: "translateY",
       from: -round1(gy),
       to: round1(gy)
@@ -2563,8 +2404,8 @@ function browReach(hh) {
   return AMPLITUDE.brow * hh;
 }
 function browBindings(side, reach) {
-  const y = side === "L" ? import_format4.StandardParameter.BrowLeftY : import_format4.StandardParameter.BrowRightY;
-  const a = side === "L" ? import_format4.StandardParameter.BrowLeftAngle : import_format4.StandardParameter.BrowRightAngle;
+  const y = side === "L" ? import_format3.StandardParameter.BrowLeftY : import_format3.StandardParameter.BrowRightY;
+  const a = side === "L" ? import_format3.StandardParameter.BrowLeftAngle : import_format3.StandardParameter.BrowRightAngle;
   return [
     {
       parameter: y,
@@ -2583,7 +2424,7 @@ var mouthFrameOf = (box) => ({
 });
 function mouthForm(mesh, box, frame = mouthFrameOf(box)) {
   const { c, half, amp: a } = frame;
-  return localWarp(import_format4.StandardParameter.MouthForm, mesh, box, [-1, 0, 1], ([x], v) => {
+  return localWarp(import_format3.StandardParameter.MouthForm, mesh, box, [-1, 0, 1], ([x], v) => {
     if (v === 0) return [0, 0];
     const u = (x - c) / half;
     const widen = v > 0 ? 0.05 : 0.03;
@@ -2593,7 +2434,7 @@ function mouthForm(mesh, box, frame = mouthFrameOf(box)) {
 function mouthOpenGrow(mesh, box) {
   const c = cx(box);
   return localWarp(
-    import_format4.StandardParameter.MouthOpen,
+    import_format3.StandardParameter.MouthOpen,
     mesh,
     box,
     [0, 1],
@@ -2602,25 +2443,38 @@ function mouthOpenGrow(mesh, box) {
 }
 function mouthWiden(mesh, box, frame = mouthFrameOf(box)) {
   const c = frame.c;
-  return localWarp(import_format4.StandardParameter.MouthOpen, mesh, box, [0, 1], ([x], v) => [
+  return localWarp(import_format3.StandardParameter.MouthOpen, mesh, box, [0, 1], ([x], v) => [
     v * (AMPLITUDE.mouthOpenWidth - 1) * (x - c),
     0
   ]);
 }
+function swayAt(b, y) {
+  return Math.min(1, Math.max(0, (b.y1 - y) / bh(b))) ** SWAY_CURVE;
+}
 function hairSway(param, mesh, box, amp) {
+  return localWarp(
+    param,
+    mesh,
+    box,
+    [-SWAY_RANGE, 0, SWAY_RANGE],
+    ([, y], v) => [v / SWAY_RANGE * amp * swayAt(box, y), 0]
+  );
+}
+function lockSway(param, mesh, box, amp, attach) {
   return localWarp(
     param,
     mesh,
     box,
     [-SWAY_RANGE, 0, SWAY_RANGE],
     ([, y], v) => {
-      const t = Math.max(0, (box.y1 - y) / bh(box));
-      return [v / SWAY_RANGE * amp * t ** SWAY_CURVE, 0];
+      const w = attach.weight(y);
+      const share = (1 - w) * swayAt(attach.box, y) + w * swayAt(box, y);
+      return [v / SWAY_RANGE * amp * share, 0];
     }
   );
 }
 function tiltHang(mesh, box, pivot, weight, deg = ROLL_DEG) {
-  return localWarp(import_format4.StandardParameter.AngleZ, mesh, box, Z_STOPS, ([x, y], v, i) => {
+  return localWarp(import_format3.StandardParameter.AngleZ, mesh, box, Z_STOPS, ([x, y], v, i) => {
     const g = weight(y, i);
     if (g === 0 || v === 0) return [0, 0];
     const a = -g * rollOf(v, deg);
@@ -2636,8 +2490,191 @@ function hairHangWeight(pivotY, bottom) {
   if (bottom >= pivotY) return () => 0;
   return (y) => HAIR_HANG * smoothstep(pivotY, bottom, y);
 }
+function lockHangWeight(pivotY, bottom, hh) {
+  return hairHangWeight(pivotY, Math.min(bottom, pivotY - LOCK_HANG_SPAN * hh));
+}
 var round1 = (v) => roundTo(v, 0.1);
 
+// src/auto-rig/roles.ts
+var import_format4 = require("@ikijs/format");
+var LIP_ROLES = ["mouth_inner", "lip_lower", "lip_upper"];
+var isLipRole = (role) => LIP_ROLES.includes(role);
+var LIP_INSIDE_ROLES = ["mouth_tongue", "mouth_teeth"];
+var isLipInsideRole = (role) => LIP_INSIDE_ROLES.includes(role);
+var SHUT_BY = new Map([
+  ["eye_L", import_format4.StandardParameter.EyeOpenLeft],
+  ["lash_lower_L", import_format4.StandardParameter.EyeOpenLeft],
+  ["eye_R", import_format4.StandardParameter.EyeOpenRight],
+  ["lash_lower_R", import_format4.StandardParameter.EyeOpenRight],
+  ...[...LIP_ROLES, ...LIP_INSIDE_ROLES].map((id) => [
+    id,
+    import_format4.StandardParameter.MouthOpen
+  ])
+]);
+var ROLE_TABLE = [
+  { role: "hair_back", family: "hair_back" },
+  { role: "body", family: "body" },
+  { role: "arm_L", family: "arm", parts: ["elbow_L", "forearm_L", "arm_L"] },
+  { role: "arm_R", family: "arm", parts: ["elbow_R", "forearm_R", "arm_R"] },
+  { role: "face", family: "face", required: true },
+  { role: "blush_L", family: "face" },
+  { role: "blush_R", family: "face" },
+  { role: "nose", family: "nose" },
+  { role: "mouth", family: "mouth" },
+  { role: "mouth_open", family: "mouth" },
+  // The lip set, back to front: the interior, the tongue and the teeth clipped
+  // to it, the lower lip's skin, the upper lip and its line over both. It
+  // folds open instead of crossfading (`mouth.ts`), so it stands in for
+  // `mouth`, never beside it.
+  { role: "mouth_inner", family: "mouth" },
+  { role: "mouth_tongue", family: "mouth" },
+  { role: "mouth_teeth", family: "mouth" },
+  { role: "lip_lower", family: "mouth" },
+  { role: "lip_upper", family: "mouth" },
+  { role: "eye_L", family: "eye_L", required: true },
+  { role: "eye_R", family: "eye_R", required: true },
+  { role: "iris_L", family: "eye_L" },
+  { role: "iris_R", family: "eye_R" },
+  { role: "pupil_L", family: "eye_L" },
+  { role: "pupil_R", family: "eye_R" },
+  { role: "highlight_L", family: "eye_L" },
+  { role: "highlight_R", family: "eye_R" },
+  { role: "lash_lower_L", family: "eye_L" },
+  { role: "lash_lower_R", family: "eye_R" },
+  { role: "lash_L", family: "eye_L" },
+  { role: "lash_R", family: "eye_R" },
+  { role: "brow_L", family: "brow_L" },
+  { role: "brow_R", family: "brow_R" },
+  // The front side locks: over the brows and lashes, under the bangs, which
+  // hide their roots.
+  { role: "hair_side_L", family: "hair_side" },
+  { role: "hair_side_R", family: "hair_side" },
+  { role: "hair_front", family: "hair_front" },
+  // Drawn above the face and the hair: a raised hand passes them.
+  { role: "forearm_pose_L", family: "forearm_pose" },
+  { role: "forearm_pose_R", family: "forearm_pose" }
+];
+var REQUIRED_ROLES = ROLE_TABLE.filter(
+  (r) => r.required
+).map((r) => r.role);
+var SPEC_BY_ROLE = new Map(ROLE_TABLE.map((r, i) => [r.role, { ...r, i }]));
+function roleSpec(role) {
+  const spec = SPEC_BY_ROLE.get(role);
+  if (spec === void 0) throw new Error(`auto-rig: unknown role "${role}"`);
+  return spec;
+}
+function partIdsOfRole(role) {
+  return roleSpec(role).parts ?? [role];
+}
+var ROLE_BY_PART = new Map(
+  ROLE_TABLE.flatMap((r) => (r.parts ?? []).map((p) => [p, r.role]))
+);
+function roleOfPart(partId) {
+  return ROLE_BY_PART.get(partId) ?? partId;
+}
+var ALIASES = {
+  eyebrow_L: "brow_L",
+  eyebrow_R: "brow_R",
+  eye_white_L: "eye_L",
+  eye_white_R: "eye_R"
+};
+function roleOf(fileName) {
+  const role = fileName.replace(/\.[^.]+$/, "").toLowerCase().replace(/[-\s]+/g, "_").replace(/_([lr])$/, (_, s) => `_${s.toUpperCase()}`);
+  return ALIASES[role] ?? role;
+}
+function checkArmsHaveBody(roles) {
+  const has = new Set(roles);
+  if (has.has("body")) return;
+  const arm = ROLE_TABLE.find((r) => r.family === "arm" && has.has(r.role));
+  if (arm !== void 0) {
+    throw new Error(
+      `auto-rig: ${arm.role} needs a body layer (an arm hangs from the body's shoulder)`
+    );
+  }
+}
+function checkSidesHaveFront(roles) {
+  const has = new Set(roles);
+  if (has.has("hair_front")) return;
+  const side = ROLE_TABLE.find(
+    (r) => r.family === "hair_side" && has.has(r.role)
+  );
+  if (side !== void 0) {
+    throw new Error(
+      `auto-rig: ${side.role} needs a hair_front layer (a side lock's root hides under the bangs)`
+    );
+  }
+}
+function checkMouth(roles) {
+  const has = new Set(roles);
+  const present = LIP_ROLES.filter((r) => has.has(r));
+  const inside = LIP_INSIDE_ROLES.filter((r) => has.has(r));
+  if (inside.length > 0 && present.length === 0) {
+    throw new Error(
+      `auto-rig: ${inside[0]} needs the lip set ${LIP_ROLES.join(", ")} (it is cut from the interior and clipped to it)`
+    );
+  }
+  if (present.length === 0) {
+    if (!has.has("mouth")) {
+      throw new Error(
+        `auto-rig: missing required role mouth (or the lip set ${LIP_ROLES.join(", ")})`
+      );
+    }
+    return;
+  }
+  if (present.length < LIP_ROLES.length) {
+    throw new Error(
+      `auto-rig: the lip set is partial: missing ${LIP_ROLES.filter((r) => !has.has(r)).join(", ")}`
+    );
+  }
+  const mixed = ["mouth", "mouth_open"].filter((r) => has.has(r));
+  if (mixed.length > 0) {
+    throw new Error(
+      `auto-rig: the lip set cannot be mixed with ${mixed.join(", ")} (the lip set replaces the mouth drawings; use one or the other)`
+    );
+  }
+}
+function checkPosesHaveArms(roles) {
+  const has = new Set(roles);
+  for (const side of ["L", "R"]) {
+    if (has.has(`forearm_pose_${side}`) && !has.has(`arm_${side}`)) {
+      throw new Error(
+        `auto-rig: forearm_pose_${side} needs an arm_${side} layer (a pose forearm hangs from its arm's elbow)`
+      );
+    }
+  }
+}
+function parseLayerRoles(fileNames) {
+  const seen = /* @__PURE__ */ new Map();
+  const out = [];
+  for (const fileName of fileNames) {
+    const role = roleOf(fileName);
+    if (!SPEC_BY_ROLE.has(role)) {
+      throw new Error(
+        `auto-rig: "${fileName}" names no known role (expected one of ${ROLE_TABLE.map((r) => r.role).join(", ")})`
+      );
+    }
+    const prior = seen.get(role);
+    if (prior !== void 0) {
+      throw new Error(
+        `auto-rig: role "${role}" is named twice ("${prior}" and "${fileName}")`
+      );
+    }
+    seen.set(role, fileName);
+    out.push({ role, fileName });
+  }
+  const missing = REQUIRED_ROLES.filter((r) => !seen.has(r));
+  if (missing.length > 0) {
+    throw new Error(
+      `auto-rig: missing required role${missing.length > 1 ? "s" : ""} ${missing.join(", ")}`
+    );
+  }
+  checkMouth(seen.keys());
+  checkArmsHaveBody(seen.keys());
+  checkPosesHaveArms(seen.keys());
+  checkSidesHaveFront(seen.keys());
+  return out;
+}
+
 // src/auto-rig/mouth.ts
 var UPPER_SHARE = 0.4;
 var CLOSED_SAG_MAX = 0.1;
@@ -3033,6 +3070,7 @@ function buildHeadFrame(layers, opts) {
   let paintedHalfAt = () => plateHalf;
   let neck;
   let ears;
+  let headHalfAt = (y) => paintedHalfAt(y);
   let headMax = plateHalf;
   let chinY = face.y0;
   let cutAt = () => face.y0 - 1;
@@ -3051,6 +3089,12 @@ function buildHeadFrame(layers, opts) {
       const t = clamp(r - i, 0, 1);
       return prof[i] + (prof[j] - prof[i]) * t;
     };
+    const readRows = (rows) => (y) => {
+      const r = canvasH / 2 - y - faceLayer.bbox.y - 0.5;
+      const i = clamp(Math.floor(r), 0, rows.length - 1);
+      const j = Math.min(i + 1, rows.length - 1);
+      return rows[i] + (rows[j] - rows[i]) * clamp(r - i, 0, 1);
+    };
     const rawRows = raw;
     const earless = (chin) => {
       const rowOf = (y) => Math.round(canvasH / 2 - y - faceLayer.bbox.y - 0.5);
@@ -3151,6 +3195,7 @@ function buildHeadFrame(layers, opts) {
         canvasH / 2 - nk.topY - faceLayer.bbox.y - 0.5
       );
       const head = earless(chinY);
+      headHalfAt = readRows(head);
       headMax = Math.max(...head);
       const outlineAt = (d) => {
         for (let r = neckRow; r >= 0; r--) {
@@ -3193,6 +3238,7 @@ function buildHeadFrame(layers, opts) {
       };
     } else {
       const head = earless(chinY);
+      headHalfAt = readRows(head);
       headMax = Math.max(...head);
       if (ears !== void 0) {
         const bottomOf = (d) => {
@@ -3240,6 +3286,7 @@ function buildHeadFrame(layers, opts) {
     chinY,
     hh,
     paintedHalfAt,
+    headHalfAt,
     wMax,
     headMax,
     hasProfile: profile !== null,
@@ -3257,6 +3304,96 @@ function buildHeadFrame(layers, opts) {
   };
 }
 
+// src/auto-rig/hair-side-room.ts
+var round3 = (v) => Math.round(v * 1e3) / 1e3;
+var signed = (v) => round3(v) + 0;
+function headEdge(ctx, land2, y, side, ax) {
+  const { frame } = ctx;
+  return land2("face", frame.axisX + side * frame.headHalfAt(y), y, ax);
+}
+var LOCKS = ["hair_side_L", "hair_side_R"];
+function hairSideRoom(ctx, land2, boxes) {
+  const out = {};
+  for (const role of LOCKS) {
+    const box = boxes[role];
+    if (box === void 0) continue;
+    const side = (box.x0 + box.x1) / 2 < ctx.frame.axisX ? -1 : 1;
+    const key = side < 0 ? "left" : "right";
+    if (out[key] !== void 0) continue;
+    out[key] = lockRoom(ctx, land2, boxes, role, box, side);
+  }
+  return out.left || out.right ? out : void 0;
+}
+function lockRoom(ctx, land2, boxes, role, box, side) {
+  const { frame } = ctx;
+  if (frame.hairRuns(role, box.y1 - 0.5) === void 0) {
+    return { role, unavailable: "no rowRuns" };
+  }
+  const room = { role };
+  const stops = farStops(side);
+  let cover;
+  for (let i = 0; i < Math.ceil(box.y1 - box.y0); i++) {
+    const y2 = box.y1 - i - 0.5;
+    if (y2 < frame.face.y0 || y2 > frame.face.y1) continue;
+    const outer2 = outerEdge(frame.hairRuns(role, y2) ?? [], frame.axisX, side);
+    if (outer2 === void 0) continue;
+    const rest = side * (outer2 - frame.axisX) - frame.headHalfAt(y2);
+    if (rest < 0) continue;
+    for (const ax of stops) {
+      const px = side * (land2(role, outer2, y2, ax) - headEdge(ctx, land2, y2, side, ax));
+      if (cover === void 0 || px < cover.px)
+        cover = { deg: ax, px, y: y2, rest };
+    }
+  }
+  if (cover !== void 0) {
+    room.cover = {
+      deg: cover.deg,
+      px: signed(cover.px),
+      y: round3(cover.y),
+      rest: signed(cover.rest)
+    };
+  }
+  const eye = side < 0 ? ctx.eyeBoxes.left : ctx.eyeBoxes.right;
+  const eyeRole = (side < 0 ? ctx.left : ctx.right).role.replace(
+    /^iris_/,
+    "eye_"
+  );
+  const y = cy(eye);
+  const runs = frame.hairRuns(role, y) ?? [];
+  const outer = outerEdge(runs, frame.axisX, side);
+  if (outer === void 0) return room;
+  const inner = outer - side * runReach(runs, outer, side).inward;
+  const lashRole = eyeRole.replace(/^eye_/, "lash_");
+  const lash = boxes[lashRole];
+  let tail;
+  for (const ax of stops) {
+    const lock = land2(role, inner, y, ax);
+    const corner = land2(eyeRole, side < 0 ? eye.x0 : eye.x1, y, ax);
+    const eyeToLock = side * (lock - corner);
+    if (tail !== void 0 && eyeToLock >= tail.eyeToLock) continue;
+    tail = {
+      deg: ax,
+      eyeToLock,
+      eyeToPlate: side * (headEdge(ctx, land2, y, side, ax) - corner)
+    };
+    if (lash !== void 0) {
+      const tip = land2(lashRole, side < 0 ? lash.x0 : lash.x1, y, ax);
+      tail.lashToLock = side * (lock - tip);
+    }
+  }
+  if (tail !== void 0) {
+    room.tail = {
+      deg: tail.deg,
+      eyeToLock: signed(tail.eyeToLock),
+      ...tail.lashToLock !== void 0 && {
+        lashToLock: signed(tail.lashToLock)
+      },
+      eyeToPlate: signed(tail.eyeToPlate)
+    };
+  }
+  return room;
+}
+
 // src/auto-rig/fields.ts
 var NOSE_TILT_DEG = 6;
 function nodDy(v, ay, hh) {
@@ -3510,6 +3647,48 @@ function hairFrontField(m) {
     return [rx, by + crownBlend(m, y) * (ry - by)];
   };
 }
+var SIDE_ROOT_BLEND = 0.2;
+function sideRootBlend(f, role, box) {
+  let rootEnd = box.y1 - (box.y1 - box.y0) / 4;
+  if (f.hairRuns(role, box.y1 - 0.5) !== void 0 && f.hairRuns("hair_front", box.y1 - 0.5) !== void 0) {
+    const shows = (y) => {
+      const lock = f.hairRuns(role, y);
+      const front = f.hairRuns("hair_front", y);
+      for (let k = 0; k < lock.length; k += 2) {
+        for (let px = lock[k]; px < lock[k + 1]; px++) {
+          if (!paints(front, px)) return true;
+        }
+      }
+      return false;
+    };
+    const rows = Array.from(
+      { length: Math.round(box.y1 - box.y0) },
+      (_, i2) => i2
+    );
+    const i = rows.findIndex((i2) => shows(box.y1 - i2 - 0.5));
+    rootEnd = i < 0 ? box.y0 : box.y1 - i;
+  }
+  const end = rootEnd - SIDE_ROOT_BLEND * f.hh;
+  return { rootEnd, weight: (y) => smoothstep(rootEnd, end, y) };
+}
+function hairSideField(m) {
+  const front = hairFrontField(m);
+  const face = faceField(m);
+  const locks = ["hair_side_L", "hair_side_R"].flatMap((role) => {
+    const box = m.boxes[role];
+    return box === void 0 ? [] : [{ box, ...sideRootBlend(m.frame, role, box) }];
+  });
+  return (x, y, ax, ay) => {
+    const lock = locks.find((l) => x >= l.box.x0 && x <= l.box.x1);
+    if (lock === void 0) return face(x, y, ax, ay);
+    const t = lock.weight(y);
+    if (t === 0) return front(x, y, ax, ay);
+    if (t === 1) return face(x, y, ax, ay);
+    const [fx, fy] = front(x, y, ax, ay);
+    const [gx, gy] = face(x, y, ax, ay);
+    return [fx * (1 - t) + gx * t, fy * (1 - t) + gy * t];
+  };
+}
 function crownBlend(m, y) {
   const top = m.frame.face.y1;
   return 1 - smoothstep(top, Math.max(top + 1, m.hairTop), y);
@@ -3930,6 +4109,8 @@ function familyField(m, family) {
       return mouthField(m);
     case "hair_front":
       return hairFrontField(m);
+    case "hair_side":
+      return hairSideField(m);
     case "hair_back":
       return hairField(m, m.hairBack, NOD.hairBack);
     case "body":
@@ -4086,16 +4267,16 @@ function strandOverlaps(ctx, land2, holdBase) {
     if (px <= 0) continue;
     out[key] = {
       deg,
-      px: round3(px),
-      hh: round3(px) / holdBase,
-      restPx: round3(restPx),
+      px: round32(px),
+      hh: round32(px) / holdBase,
+      restPx: round32(restPx),
       // A fringe spanning the face has no side to hold the iris clear of.
       held: strand.runFace !== null && px <= restPx + STRAND_SLACK
     };
   }
   return out.left || out.right ? out : void 0;
 }
-var round3 = (v) => Math.round(v * 1e3) / 1e3;
+var round32 = (v) => Math.round(v * 1e3) / 1e3;
 var STRAND_SLACK = 0.5;
 function bisect(f, lo, hi, it = 50) {
   for (let i = 0; i < it; i++) {
@@ -4310,7 +4491,7 @@ function turnReport(ctx, fit, rendered) {
   const plate = depth(m.face);
   const w = frame.paintedHalfAt(frame.eyeY);
   const report = {
-    radius: round3(w * w / (2 * Math.max(1e-3, eye - plate))),
+    radius: round32(w * w / (2 * Math.max(1e-3, eye - plate))),
     holdBase: hb,
     depths: {
       eye: round4(eye / hb),
@@ -4326,6 +4507,8 @@ function turnReport(ctx, fit, rendered) {
   };
   const overlap = strandOverlaps(ctx, rendered, hb);
   if (overlap !== void 0) report.strandOverlap = overlap;
+  const hairSide = hairSideRoom(ctx, rendered, m.boxes);
+  if (hairSide !== void 0) report.hairSide = hairSide;
   return report;
 }
 var round4 = (v) => Math.round(v * 1e4) / 1e4;
@@ -4481,7 +4664,7 @@ var RIG_PLAN_FIELDS = [
     fitBy: null,
     provisional: false,
     migratedFrom: "outlineFollow",
-    what: "the front hair's outer edge's share where it draws the head's outline (0: the outline holds, though where back hair paints behind it, it may ride further, as far as that back hair reaches; at hair.follow the side locks ride whole)"
+    what: "the front hair's outer edge's share where it draws the head's outline (0: the outline holds, though where back hair paints behind it, it may ride further, as far as that back hair reaches; at hair.follow the front hair's side strands ride whole)"
   },
   {
     path: "hair.sway",
@@ -5535,6 +5718,7 @@ function checkLayers(layers, canvas) {
   }
   checkArmsHaveBody(seen);
   checkPosesHaveArms(seen);
+  checkSidesHaveFront(seen);
 }
 function checkHeadEdges(edges, byRole) {
   if (edges === void 0) return;
@@ -6259,6 +6443,10 @@ var MESH_CELLS = {
   face: { px: 28, min: 4, max: 24 },
   // The front hair eases from riding the face to holding the outline.
   hair_front: { px: 32, min: 3, max: 24 },
+  // A side lock's rows come from `sideLockGrid`: even ones, plus the root
+  // band's (`sideRootBlend`), which a long lock's coarse cells would straddle.
+  hair_side_L: { px: 20, min: 3, max: 24 },
+  hair_side_R: { px: 20, min: 3, max: 24 },
   hair_back: { px: 56, min: 3, max: 18 }
 };
 var NECK_CELLS = { px: 20, min: 3, max: 12 };
@@ -6310,7 +6498,18 @@ function generateIkiFromLayerSet(layers, canvas, options = {}) {
   const solveFrame = buildHeadFrame(layers, frameOptions);
   const ctx = solveContext(solveFrame, byRole, turnOptions, hasNose);
   const boxes = Object.fromEntries(
-    ["eye_L", "eye_R", "iris_L", "iris_R", "brow_L", "brow_R"].filter(has).map((r) => [r, box(r)])
+    [
+      "eye_L",
+      "eye_R",
+      "iris_L",
+      "iris_R",
+      "brow_L",
+      "brow_R",
+      "hair_side_L",
+      "hair_side_R",
+      "lash_L",
+      "lash_R"
+    ].filter(has).map((r) => [r, box(r)])
   );
   const landmarks = {
     boxes,
@@ -6515,6 +6714,8 @@ function buildPart(spec, b, order, frame, byRole, plan, frontGrid, lips) {
     headStart = fm.headStart;
   } else if (spec.role === "hair_front") {
     mesh = columnMesh(b, frontGrid);
+  } else if (spec.role === "hair_side_L" || spec.role === "hair_side_R") {
+    mesh = columnMesh(b, sideLockGrid(b, frame, spec.role));
   } else if (lips !== void 0 && (isLipRole(spec.role) || isLipInsideRole(spec.role))) {
     ({ mesh, xs: knotXs } = mouthMesh(b, lips.knots));
   } else if (spec.family !== "body") {
@@ -6529,6 +6730,7 @@ function buildPart(spec, b, order, frame, byRole, plan, frontGrid, lips) {
   const side = spec.role.endsWith("_L") ? "L" : "R";
   const eyeOpen = side === "L" ? import_format12.StandardParameter.EyeOpenLeft : import_format12.StandardParameter.EyeOpenRight;
   const hh = frame.hh;
+  const swayAmp = plan.hair.sway * plan.profile.AMPLITUDE.sway * hh;
   switch (spec.role) {
     case "face":
       if (region?.some((r) => r === "neck")) {
@@ -6665,18 +6867,30 @@ function buildPart(spec, b, order, frame, byRole, plan, frontGrid, lips) {
     case "hair_front":
     case "hair_back":
       if (byRole.has("hair_front")) {
-        const amp = plan.hair.sway * plan.profile.AMPLITUDE.sway * hh;
         if (spec.role === "hair_front") {
           warps.push(
-            hairSway(import_format12.StandardParameter.HairSwayX, mesh, b, amp),
-            hairSway(import_format12.StandardParameter.HairSwayZ, mesh, b, amp)
+            hairSway(import_format12.StandardParameter.HairSwayX, mesh, b, swayAmp),
+            hairSway(import_format12.StandardParameter.HairSwayZ, mesh, b, swayAmp)
           );
         } else {
-          warps.push(hairSway(import_format12.StandardParameter.HairBackSway, mesh, b, amp));
+          warps.push(hairSway(import_format12.StandardParameter.HairBackSway, mesh, b, swayAmp));
         }
       }
       warps.push(tiltHang(mesh, b, pivot, hairHangWeight(frame.chinY, b.y0)));
       break;
+    case "hair_side_L":
+    case "hair_side_R": {
+      const attach = {
+        box: box("hair_front"),
+        weight: sideRootBlend(frame, spec.role, b).weight
+      };
+      warps.push(
+        lockSway(import_format12.StandardParameter.HairSwayX, mesh, b, swayAmp, attach),
+        lockSway(import_format12.StandardParameter.HairSwayZ, mesh, b, swayAmp, attach),
+        tiltHang(mesh, b, pivot, lockHangWeight(frame.chinY, b.y0, hh))
+      );
+      break;
+    }
   }
   if (warps.length > 0) part.warps = warps;
   if (bindings.length > 0) part.bindings = bindings;
@@ -6733,9 +6947,34 @@ function hairFrontGrid(b, frame, boxes) {
   }
   return { xs, ys };
 }
+var BLEND_ROWS = 3;
+function sideLockGrid(b, frame, role) {
+  const cells = MESH_CELLS[role];
+  const px = Math.min(cells.px, meshScale(role, frame));
+  const cols = cellsFor(bw(b), px, cells.min, cells.max);
+  const rows = cellsFor(bh(b), px, cells.min, cells.max);
+  const xs = Array.from(
+    { length: cols + 1 },
+    (_, c) => b.x0 + bw(b) * c / cols
+  );
+  const ys = Array.from(
+    { length: rows + 1 },
+    (_, r) => b.y1 - bh(b) * r / rows
+  );
+  const { rootEnd } = sideRootBlend(frame, role, b);
+  const end = rootEnd - SIDE_ROOT_BLEND * frame.hh;
+  for (let i = 0; i <= BLEND_ROWS + 1; i++) {
+    const y = rootEnd + (end - rootEnd) * i / (BLEND_ROWS + 1);
+    if (y > b.y0 + 0.25 && y < b.y1 - 0.25 && ys.every((v) => Math.abs(v - y) > 0.25))
+      ys.push(y);
+  }
+  return { xs, ys: ys.sort((p, q) => q - p) };
+}
 function meshScale(role, frame) {
   switch (role) {
     case "hair_front":
+    case "hair_side_L":
+    case "hair_side_R":
     case "hair_back":
       return Math.max(2, (frame.shellRight - frame.shellLeft) / 9);
     default: