@ikijs/editor 0.6.0 → 0.7.0

package/dist/index.mjs

@@ -1778,6 +1778,125 @@ function validateLayerInputs(layers, canvas) {
     }
   }
 }
+function validateStrandEdges(layers, strandEdges) {
+  if (strandEdges === void 0) return;
+  const where = "auto-rig: validateStrandEdges: strandEdges";
+  const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+  if (!isPlainObject(strandEdges)) {
+    throw new Error(
+      `${where} must be a plain object with optional left / right sides`
+    );
+  }
+  for (const key of ["left", "right"]) {
+    const raw = strandEdges[key];
+    if (raw === void 0) continue;
+    const path = `${where}.${key}`;
+    if (!isPlainObject(raw)) {
+      throw new Error(`${path} must be a plain object`);
+    }
+    for (const field of ["y", "irisOuter", "irisInner", "runOuter"]) {
+      const v = raw[field];
+      if (typeof v !== "number" || !Number.isFinite(v)) {
+        throw new Error(
+          `${path}.${field} is ${String(v)}, not a finite number`
+        );
+      }
+    }
+    const rawFace = raw.runFace;
+    if (rawFace !== null && (typeof rawFace !== "number" || !Number.isFinite(rawFace))) {
+      throw new Error(
+        `${path}.runFace is ${String(rawFace)}, not a finite number or null`
+      );
+    }
+    const { y, irisOuter, irisInner, runOuter, runFace } = raw;
+    const cropOf = (role) => {
+      const layer = layers.find((l) => l.role === role);
+      if (layer === void 0) {
+        throw new Error(
+          `${path} needs a "${role}" layer to be measured on, and this layer set has none`
+        );
+      }
+      const t = bboxToTransform(layer.bbox, layer.canvasW, layer.canvasH, role);
+      return {
+        role,
+        x: t.x,
+        left: t.x - layer.cropW / 2,
+        right: t.x + layer.cropW / 2,
+        bottom: t.y - layer.cropH / 2,
+        top: t.y + layer.cropH / 2
+      };
+    };
+    const hair = cropOf("hair_front");
+    const [lowIris, highIris] = [cropOf("iris_L"), cropOf("iris_R")].sort(
+      (a, b) => a.x - b.x
+    );
+    const sign = key === "left" ? -1 : 1;
+    const iris = key === "left" ? lowIris : highIris;
+    const other = key === "left" ? highIris : lowIris;
+    const fail = (field, value, why) => new Error(`${path}.${field} (${value}) ${why}`);
+    for (const crop of [iris, hair]) {
+      if (y < crop.bottom || y > crop.top) {
+        throw fail(
+          "y",
+          y,
+          `lies outside the "${crop.role}" crop's rows (${crop.bottom}\u2026${crop.top})`
+        );
+      }
+    }
+    for (const [field, x] of [
+      ["irisOuter", irisOuter],
+      ["irisInner", irisInner]
+    ]) {
+      if (x < iris.left || x > iris.right) {
+        throw fail(
+          field,
+          x,
+          `lies outside the "${iris.role}" crop's columns (${iris.left}\u2026${iris.right})`
+        );
+      }
+    }
+    if (sign * (irisOuter - irisInner) <= 0) {
+      throw fail(
+        "irisOuter",
+        irisOuter,
+        `must lie strictly outward of strandEdges.${key}.irisInner (${irisInner})`
+      );
+    }
+    for (const [field, x] of [
+      ["runOuter", runOuter],
+      ["runFace", runFace]
+    ]) {
+      if (x !== null && (x < hair.left || x > hair.right)) {
+        throw fail(
+          field,
+          x,
+          `lies outside the "hair_front" crop's columns (${hair.left}\u2026${hair.right})`
+        );
+      }
+    }
+    if (sign * (runOuter - iris.x) <= 0) {
+      throw fail(
+        "runOuter",
+        runOuter,
+        `must lie strictly outward of the "${iris.role}" crop's centre (${iris.x})`
+      );
+    }
+    if (runFace !== null && sign * (runOuter - runFace) <= 0) {
+      throw fail(
+        "runOuter",
+        runOuter,
+        `must lie strictly outward of strandEdges.${key}.runFace (${runFace})`
+      );
+    }
+    if (runFace !== null && sign * (runFace - other.x) <= 0) {
+      throw fail(
+        "runFace",
+        runFace,
+        `must lie strictly on this side of the "${other.role}" crop's centre (${other.x}); a run that reaches it has no face-side end here, which is runFace null`
+      );
+    }
+  }
+}
 function generateGridPoints(cols, rows, minX, maxX, minY, maxY) {
   const pts = [];
   for (let row = 0; row <= rows; row++) {
@@ -1934,21 +2053,26 @@ function turnSurface(spec) {
     )
   };
 }
-function bakeTurnGroupWarp2D(grid, parameterX, parameterY, surface, shiftAt) {
+function bakeTurnGroupWarp2D(grid, parameterX, parameterY, surface, shiftAt, anchor) {
   const STOPS = [...HEAD_TURN_STOPS];
   const pointCount = grid.points.length / 2;
   const keyforms2d = [];
   for (const angleY of STOPS) {
     for (const angleX of STOPS) {
       const shift = shiftAt(angleX);
+      const mapAt = (nodeY) => surface.mapAt(angleX, nodeY);
       const offsets = [];
       for (let i = 0; i < pointCount; i++) {
         const x = grid.points[i * 2];
         const y = grid.points[i * 2 + 1];
-        offsets.push(
-          angleX === 0 ? 0 : surface.mapAt(angleX, y).mapX(x + shift) - x,
-          angleY === 0 ? 0 : surface.nodBendAt(y, angleY)
-        );
+        const nodDy = angleY === 0 ? 0 : surface.nodBendAt(y, angleY);
+        if (angleX === 0) {
+          offsets.push(0, nodDy);
+          continue;
+        }
+        const landed = groupNodeLanding(anchor, mapAt, angleX, shift, x, y);
+        const turnDy = landed.y - y;
+        offsets.push(landed.x - x, angleY === 0 ? turnDy : turnDy + nodDy);
       }
       keyforms2d.push({ offsets });
     }
@@ -2068,6 +2192,22 @@ function carrierLandingX(carrier, nodeLanding, px, py) {
     py
   );
 }
+function groupNodeLanding(anchor, mapAt, deg, shift, nodeX, nodeY) {
+  if (anchor === void 0) {
+    return { x: mapAt(nodeY).mapX(nodeX + shift), y: nodeY };
+  }
+  const anchorRow = mapAt(anchor.y);
+  const pivotX = anchorRow.mapX(anchor.x + shift);
+  const dx = mapAt(nodeY).mapX(nodeX) - anchorRow.mapX(anchor.x);
+  const dy = nodeY - anchor.y;
+  const phi = anchor.tiltDeg * deg / HEAD_TURN_MAX_DEG * (Math.PI / 180);
+  const cos = Math.cos(phi);
+  const sin = Math.sin(phi);
+  return {
+    x: pivotX + cos * dx - sin * dy,
+    y: anchor.y + sin * dx + cos * dy
+  };
+}
 function rowMapsOf(surface) {
   const maps = /* @__PURE__ */ new Map();
   return (deg, nodeY) => {
@@ -2221,11 +2361,12 @@ function eyeRowOf(landmarks, fallback) {
 }
 var TURN_BISECT_STEPS = 40;
 var TURN_DEPTH_EPS = 1e-6;
-function landmarkLandingX(landmark, mapAt, shift, px, py) {
-  if (landmark.carrier === void 0) return mapAt(py).mapX(px + shift);
+function landmarkLandingX(landmark, mapAt, deg, shift, px, py) {
+  const { carrier } = landmark;
+  if (carrier === void 0) return mapAt(py).mapX(px + shift);
   return carrierLandingX(
-    landmark.carrier,
-    (nodeX, nodeY) => mapAt(nodeY).mapX(nodeX + shift),
+    carrier,
+    (nodeX, nodeY) => groupNodeLanding(carrier.anchor, mapAt, deg, shift, nodeX, nodeY).x,
     px,
     py
   );
@@ -2234,22 +2375,47 @@ function familyReachPx(landmarks, plateEdgeX) {
   const farEdge = Math.min(...landmarks.map((l) => l.x - l.w / 2));
   return Math.max(0, farEdge - plateEdgeX);
 }
-function solveTurnDepthSigned(target, landmarks, unit, mapAt, plateEdgeX) {
+function familyDepthCap(landmarks, plateEdgeX, unit) {
+  return familyReachPx(landmarks, plateEdgeX) / unit;
+}
+function solveTurnDepthSigned(target, landmarks, unit, mapAt, plateEdgeX, maxDepth) {
   if (landmarks.length === 0) {
     throw new Error("auto-rig: solveTurnDepth: no landmark to slide");
   }
-  const cap = familyReachPx(landmarks, plateEdgeX) / unit;
+  const plateCap = familyDepthCap(landmarks, plateEdgeX, unit);
+  const cap = maxDepth === void 0 ? plateCap : Math.min(plateCap, maxDepth);
   const achieved = (d) => landmarks.reduce(
-    (sum, l) => sum + (landmarkLandingX(l, mapAt, -d * unit, l.x, l.y ?? 0) - l.x),
+    (sum, l) => sum + (landmarkLandingX(
+      l,
+      mapAt,
+      -HEAD_TURN_MAX_DEG,
+      -d * unit,
+      l.x,
+      l.y ?? 0
+    ) - l.x),
     0
   ) / landmarks.length;
   const atCap = achieved(cap);
   const atRest = achieved(0);
   const attainable = [atCap, atRest];
-  if (target > atRest + TURN_DEPTH_EPS)
-    return { reached: false, depth: 0, achieved: atRest, attainable };
-  if (target < atCap - TURN_DEPTH_EPS)
-    return { reached: false, depth: cap, achieved: atCap, attainable };
+  if (target > atRest + TURN_DEPTH_EPS) {
+    return {
+      reached: false,
+      depth: 0,
+      achieved: atRest,
+      attainable,
+      limit: "floor"
+    };
+  }
+  if (target < atCap - TURN_DEPTH_EPS) {
+    return {
+      reached: false,
+      depth: cap,
+      achieved: atCap,
+      attainable,
+      limit: "cap"
+    };
+  }
   const clampedTarget = Math.min(Math.max(target, atCap), atRest);
   let lo = 0;
   let hi = cap;
@@ -2279,7 +2445,7 @@ function hairFrontHoldTarget(x, y, deg, faceCenterX, plateLandingAt, edgeAt, hol
   }
   return x + side * (holdEdge - holdBase);
 }
-function hairFrontLandingAt(x, y, hairFront, holdTargetAt, leadTipShift) {
+function hairFrontLandingAt(x, y, hairFront, holdTargetAt, leadShift) {
   const { cols, rows } = meshCellsFor(hairFront.cropW, hairFront.cropH);
   const top = hairFront.centerY + hairFront.cropH / 2;
   return renderedLandingX(
@@ -2294,7 +2460,7 @@ function hairFrontLandingAt(x, y, hairFront, holdTargetAt, leadTipShift) {
       scaleY: 1,
       rotation: 0
     },
-    (vx, vy) => holdTargetAt(vx, vy) - leadTipShift * Math.pow((top - vy) / hairFront.cropH, HAIR_SWAY_CURL),
+    (vx, vy) => holdTargetAt(vx, vy) + leadShift * Math.pow((top - vy) / hairFront.cropH, HAIR_SWAY_CURL),
     x,
     y
   );
@@ -2327,6 +2493,19 @@ function aitken(x0, x1, x2, cap) {
   const x = x2 - d2 * d2 / denominator;
   return Number.isFinite(x) ? Math.min(cap, Math.max(0, x)) : x2;
 }
+function strandDepthCap(margins, plateCap) {
+  const holds = (depth) => margins.every((m) => m(depth) >= 0);
+  if (holds(plateCap)) return plateCap;
+  if (!holds(0)) return void 0;
+  let lo = 0;
+  let hi = plateCap;
+  for (let i = 0; i < TURN_BISECT_STEPS; i++) {
+    const mid = (lo + hi) / 2;
+    if (holds(mid)) lo = mid;
+    else hi = mid;
+  }
+  return lo;
+}
 function evaluateTurnCandidate(ctx, radius) {
   const surfaceAt = (travel) => turnSurface({
     faceCenterX: ctx.faceCenterX,
@@ -2350,7 +2529,104 @@ function evaluateTurnCandidate(ctx, radius) {
     return edge === void 0 ? ctx.headHalfWidth : side * (edge - ctx.faceCenterX);
   };
   const unit = headTurnParallaxUnit(radius);
+  const plateCapOf = (marks) => familyDepthCap(marks, ctx.plateEdgeX, unit);
+  const eyePlateCap = plateCapOf(ctx.landmarks.eye);
   const leadTipShift = ctx.hairFrontSilhouette === void 0 ? 0 : HAIR_FRONT_DEPTH * unit;
+  const bangsLandingAt = (hold, plateLandingAt, deg, leadShift, x, y) => hairFrontLandingAt(
+    x,
+    y,
+    ctx.hairFrontSilhouette,
+    (vx, vy) => hairFrontHoldTarget(
+      vx,
+      vy,
+      deg,
+      ctx.faceCenterX,
+      plateLandingAt,
+      ctx.edgeAt,
+      hold.holdBase,
+      hold.holdEdgeAt(deg)
+    ),
+    leadShift
+  );
+  const strandStopsOn = (hold) => {
+    const rowMaps = rowMapsOf(hold.surface);
+    const plateLandingAt = plateLandingOn(ctx.plate, rowMaps);
+    return (ctx.strands ?? []).map((strand) => {
+      const iris = {
+        x: strand.carrier.part.x,
+        w: strand.carrier.part.cropW,
+        carrier: strand.carrier
+      };
+      const stops = HEAD_TURN_STOPS.filter(
+        (deg) => Math.sign(deg) === strand.side
+      ).map((deg) => {
+        const runAt = (x) => bangsLandingAt(
+          hold,
+          plateLandingAt,
+          deg,
+          leadTipShift * deg / HEAD_TURN_MAX_DEG,
+          x,
+          strand.y
+        );
+        return {
+          deg,
+          runOuter: runAt(strand.runOuter),
+          runFace: strand.runFace === null ? null : runAt(strand.runFace),
+          irisAt: (depth, x) => landmarkLandingX(
+            iris,
+            (y) => rowMaps(deg, y),
+            deg,
+            depth * unit * deg / HEAD_TURN_MAX_DEG,
+            x,
+            strand.y
+          )
+        };
+      });
+      const { runFace } = strand;
+      if (runFace === null) return { strand, stops, margins: void 0 };
+      const allowance = Math.min(0, strand.side * (runFace - strand.irisOuter));
+      const margins = stops.map(
+        (stop) => (depth) => strand.side * (stop.runFace - stop.irisAt(depth, strand.irisOuter)) - allowance
+      );
+      return { strand, stops, margins };
+    });
+  };
+  const strandOverlapOf = (sides, depth) => {
+    const overlap = {};
+    for (const { strand, stops, margins } of sides) {
+      const s = strand.side;
+      const covered = (irisOuter, irisInner, runOuter, runFace) => Math.max(
+        0,
+        Math.min(s * irisOuter, s * runOuter) - Math.max(s * irisInner, runFace === null ? -Infinity : s * runFace)
+      );
+      let worst;
+      for (const stop of stops) {
+        const px = covered(
+          stop.irisAt(depth, strand.irisOuter),
+          stop.irisAt(depth, strand.irisInner),
+          stop.runOuter,
+          stop.runFace
+        );
+        if (px > 0 && (worst === void 0 || px > worst.px)) {
+          worst = { deg: stop.deg, px };
+        }
+      }
+      if (worst === void 0) continue;
+      overlap[s < 0 ? "left" : "right"] = {
+        deg: worst.deg,
+        px: worst.px,
+        hh: worst.px / ctx.hh,
+        restPx: covered(
+          strand.irisOuter,
+          strand.irisInner,
+          strand.runOuter,
+          strand.runFace
+        ),
+        held: margins !== void 0 && margins.every((m) => m(depth) >= 0)
+      };
+    }
+    return overlap.left === void 0 && overlap.right === void 0 ? void 0 : overlap;
+  };
   const evaluateHold = (ratio, depths2) => {
     const holdEdgeFrom = (base) => (deg) => base * (1 + (ratio - 1) * Math.abs(deg) / HEAD_TURN_MAX_DEG);
     const travel = ctx.headHalfWidth === void 0 ? ctx.travel : Math.min(
@@ -2400,21 +2676,13 @@ function evaluateTurnCandidate(ctx, radius) {
       if (edge !== void 0) return edge;
       return ctx.headHalfWidth !== void 0 || ctx.hairFrontSilhouette === void 0 ? ctx.faceCenterX + side * holdBase : ctx.hairFrontSilhouette.x + side * ctx.hairFrontSilhouette.cropW / 2;
     };
-    const hairFrontAt = (x) => ctx.hairFrontSilhouette === void 0 ? x : hairFrontLandingAt(
+    const hairFrontAt = (x) => ctx.hairFrontSilhouette === void 0 ? x : bangsLandingAt(
+      { holdBase, holdEdgeAt },
+      plateLandingAt,
+      -HEAD_TURN_MAX_DEG,
+      -leadTipShift,
       x,
-      ctx.eyeRowY,
-      ctx.hairFrontSilhouette,
-      (vx, vy) => hairFrontHoldTarget(
-        vx,
-        vy,
-        -HEAD_TURN_MAX_DEG,
-        ctx.faceCenterX,
-        plateLandingAt,
-        ctx.edgeAt,
-        holdBase,
-        holdEdgeAt(-HEAD_TURN_MAX_DEG)
-      ),
-      leadTipShift
+      ctx.eyeRowY
     );
     const landingOfRole = (role, x) => {
       if (role === "hair_front") return hairFrontAt(x);
@@ -2434,7 +2702,14 @@ function evaluateTurnCandidate(ctx, radius) {
         const shift = role === "face" ? 0 : -depths2[turnFamily(role)] * unit;
         return carrierLandingX(
           carrier,
-          (nodeX, nodeY) => mapAt(nodeY).mapX(nodeX + shift),
+          (nodeX, nodeY) => groupNodeLanding(
+            carrier.anchor,
+            mapAt,
+            -HEAD_TURN_MAX_DEG,
+            shift,
+            nodeX,
+            nodeY
+          ).x,
           x,
           ctx.eyeRowY
         );
@@ -2575,12 +2850,25 @@ function evaluateTurnCandidate(ctx, radius) {
         "auto-rig: evaluateTurnCandidate: the hold it settled on folds"
       );
     }
+    const strandSides = ctx.strands === void 0 ? void 0 : strandStopsOn(hold);
+    let strandFeasible = true;
+    let maxDepth;
+    if (strandSides !== void 0) {
+      const margins = strandSides.map((s) => s.margins);
+      const cap = margins.every((m) => m !== void 0) ? strandDepthCap(
+        margins.flatMap((m) => m),
+        eyePlateCap
+      ) : void 0;
+      strandFeasible = cap !== void 0;
+      maxDepth = cap ?? 0;
+    }
     const eye = solveTurnDepthSigned(
       hold.silhouetteCenterShift - ctx.eyeShift * ctx.hh,
       ctx.landmarks.eye,
       unit,
       hold.mapAt,
-      ctx.plateEdgeX
+      ctx.plateEdgeX,
+      maxDepth
     );
     const features = solveFeatureDepths(
       ctx,
@@ -2601,25 +2889,19 @@ function evaluateTurnCandidate(ctx, radius) {
         seed = depths;
         depths = solved;
       } else {
-        const capOf = (marks) => familyReachPx(marks, ctx.plateEdgeX) / unit;
         depths = {
-          eye: aitken(
-            seed.eye,
-            depths.eye,
-            solved.eye,
-            capOf(ctx.landmarks.eye)
-          ),
+          eye: aitken(seed.eye, depths.eye, solved.eye, eyePlateCap),
           nose: aitken(
             seed.nose,
             depths.nose,
             solved.nose,
-            capOf(ctx.landmarks.nose)
+            plateCapOf(ctx.landmarks.nose)
           ),
           mouth: aitken(
             seed.mouth,
             depths.mouth,
             solved.mouth,
-            capOf(ctx.landmarks.mouth)
+            plateCapOf(ctx.landmarks.mouth)
           )
         };
         seed = void 0;
@@ -2638,7 +2920,7 @@ function evaluateTurnCandidate(ctx, radius) {
     if (silhouetteClamped && !ctx.clampSilhouetteRatio) {
       return silhouetteMiss(span);
     }
-    if (!eye.reached && !ctx.clampEyeShift) {
+    if (!eye.reached && eye.limit === "floor" && !ctx.clampEyeShift) {
       return {
         blocked: "eyeShift",
         // eyeShift is a MAGNITUDE (the sign is ignored — see TurnTargets), so
@@ -2651,9 +2933,24 @@ function evaluateTurnCandidate(ctx, radius) {
       };
     }
     const eyeShiftPx = -eye.depth * unit;
-    const scaleOf = (l) => (landmarkLandingX(l, mapAt, eyeShiftPx, l.x + l.w / 2, l.y ?? 0) - landmarkLandingX(l, mapAt, eyeShiftPx, l.x - l.w / 2, l.y ?? 0)) / l.w;
+    const scaleOf = (l) => (landmarkLandingX(
+      l,
+      mapAt,
+      -HEAD_TURN_MAX_DEG,
+      eyeShiftPx,
+      l.x + l.w / 2,
+      l.y ?? 0
+    ) - landmarkLandingX(
+      l,
+      mapAt,
+      -HEAD_TURN_MAX_DEG,
+      eyeShiftPx,
+      l.x - l.w / 2,
+      l.y ?? 0
+    )) / l.w;
     const far = ctx.landmarks.eye.reduce((a, b) => b.x < a.x ? b : a);
     const near = ctx.landmarks.eye.reduce((a, b) => b.x > a.x ? b : a);
+    const strandOverlap = strandSides === void 0 ? void 0 : strandOverlapOf(strandSides, eye.depth);
     return {
       radius,
       ratio: scaleOf(far) / scaleOf(near),
@@ -2668,7 +2965,9 @@ function evaluateTurnCandidate(ctx, radius) {
       mouth: features.mouth,
       silhouetteClamped,
       silhouetteCenterShift,
-      renderedSilhouetteRatio
+      renderedSilhouetteRatio,
+      strandFeasible,
+      ...strandOverlap === void 0 ? {} : { strandOverlap }
     };
   }
 }
@@ -2705,6 +3004,9 @@ function sweepTurnRadii(ctx) {
     unsettled
   };
 }
+function runHolds(run, ratio) {
+  return ratio >= run.ratios[0] - TURN_DEPTH_EPS && ratio <= run.ratios[1] + TURN_DEPTH_EPS;
+}
 function ratioClusters(candidates) {
   const clusters = [];
   let run = [];
@@ -2727,7 +3029,7 @@ function ratioClusters(candidates) {
   close();
   return clusters;
 }
-function fitTurnRadius(ctx, candidates, target) {
+function fitTurnRadius(ctx, candidates, target, accept) {
   let lo = candidates[0];
   let hi = candidates[candidates.length - 1];
   for (let i = candidates.length - 2; i >= 0; i--) {
@@ -2737,13 +3039,42 @@ function fitTurnRadius(ctx, candidates, target) {
       break;
     }
   }
+  return bisectTurnRadius(
+    lo,
+    hi,
+    target,
+    (radius) => {
+      const mid = evaluateTurnCandidate(ctx, radius);
+      return "blocked" in mid ? void 0 : mid;
+    },
+    accept
+  );
+}
+function bisectTurnRadius(lo, hi, target, evaluate, accept) {
+  if (!accept(lo) || !accept(hi)) {
+    throw new Error(
+      "auto-rig: bisectTurnRadius: a bracket end is not accepted"
+    );
+  }
+  const miss = (c) => Math.abs(c.ratio - target);
+  let nearest = miss(lo) <= miss(hi) ? lo : hi;
   for (let i = 0; i < TURN_BISECT_STEPS; i++) {
-    const mid = evaluateTurnCandidate(ctx, Math.sqrt(lo.radius * hi.radius));
-    if ("blocked" in mid) break;
+    const mid = evaluate(Math.sqrt(lo.radius * hi.radius));
+    if (mid === void 0) break;
+    if (accept(mid) && miss(mid) < miss(nearest)) nearest = mid;
     if ((mid.ratio - target) * (lo.ratio - target) <= 0) hi = mid;
     else lo = mid;
   }
-  return Math.abs(lo.ratio - target) <= Math.abs(hi.ratio - target) ? lo : hi;
+  if (accept(lo) && accept(hi)) return miss(lo) <= miss(hi) ? lo : hi;
+  return nearest;
+}
+function strandPreferredCandidates(candidates, farEyeRatio) {
+  const feasible = candidates.filter((c) => c.strandFeasible);
+  if (feasible.length === candidates.length) return candidates;
+  const holds = ratioClusters(feasible).some(
+    (run) => runHolds(run, farEyeRatio)
+  );
+  return holds ? feasible : candidates;
 }
 function solveFeatureDepths(ctx, eyeShift, unit, mapAt, silhouetteCenterShift) {
   const solve = (measured, marks, share) => solveTurnDepthSigned(
@@ -2758,13 +3089,38 @@ function solveFeatureDepths(ctx, eyeShift, unit, mapAt, silhouetteCenterShift) {
     mouth: solve(ctx.mouthShift, ctx.landmarks.mouth, MOUTH_SHIFT_SHARE)
   };
 }
-function solveTurnModel(targets, landmarks, lattice, faceCenterX, faceHalfWidth, faceCenterY, nodRadius, carriers, profile, hairFront, headEdges) {
+function solveTurnModel(targets, landmarks, lattice, faceCenterX, faceHalfWidth, faceCenterY, nodRadius, carriers, profile, hairFront, headEdges, strandEdges) {
   if (targets.headHalfWidth !== void 0 && targets.headHalfWidth <= faceHalfWidth) {
     throw new TurnTargetError(
       `auto-rig: turnTargets.headHalfWidth (${targets.headHalfWidth}) must be wider than the face plate's own half-width (${faceHalfWidth})`
     );
   }
   const eyeRowY = eyeRowOf(landmarks, faceCenterY);
+  let strands;
+  const strandSides = ["left", "right"].filter(
+    (key) => strandEdges?.[key] !== void 0
+  );
+  if (strandSides.length > 0) {
+    if (hairFront === void 0) {
+      throw new Error(
+        "auto-rig: solveTurnModel: strandEdges was given, but there is no hair_front to land its runs on"
+      );
+    }
+    const irises = ["iris_L", "iris_R"].map((role) => carriers.get(role)).filter((c) => c !== void 0).sort((a, b) => a.part.x - b.part.x);
+    strands = strandSides.map((key) => {
+      const carrier = irises.length === 2 ? irises[key === "left" ? 0 : 1] : void 0;
+      if (carrier === void 0) {
+        throw new Error(
+          `auto-rig: solveTurnModel: strandEdges.${key} has no iris carrier to land`
+        );
+      }
+      return {
+        ...strandEdges[key],
+        side: key === "left" ? -1 : 1,
+        carrier
+      };
+    });
+  }
   const ctx = {
     landmarks,
     lattice,
@@ -2796,9 +3152,9 @@ function solveTurnModel(targets, landmarks, lattice, faceCenterX, faceHalfWidth,
     clampSilhouetteRatio: targets.defaulted.has("silhouetteRatio"),
     hairFrontSilhouette: hairFront,
     // A companion to a MEASURED headHalfWidth only — see its own doc.
-    headEdges: targets.headHalfWidth === void 0 ? void 0 : headEdges
+    headEdges: targets.headHalfWidth === void 0 ? void 0 : headEdges,
+    strands
   };
-  const clamped = [];
   const clampInto = (value, [lo, hi]) => Math.min(Math.max(value, lo), hi);
   const pass = sweepTurnRadii(ctx);
   if (pass.candidates.length === 0) {
@@ -2829,92 +3185,107 @@ function solveTurnModel(targets, landmarks, lattice, faceCenterX, faceHalfWidth,
       attainable: pass.heldRatioLower === Infinity || pass.heldRatioUpper === -Infinity ? void 0 : [pass.heldRatioLower, pass.heldRatioUpper]
     };
   }
-  const clusters = ratioClusters(pass.candidates);
-  const distanceTo = (c) => Math.max(
-    c.ratios[0] - targets.farEyeRatio,
-    targets.farEyeRatio - c.ratios[1],
-    0
-  );
-  let farEyeRatio = targets.farEyeRatio;
-  let cluster = clusters.find(
-    (c) => farEyeRatio >= c.ratios[0] - TURN_DEPTH_EPS && farEyeRatio <= c.ratios[1] + TURN_DEPTH_EPS
-  );
-  if (cluster === void 0) {
-    cluster = clusters.reduce(
-      (a, b) => distanceTo(b) < distanceTo(a) ? b : a
+  const fitFrom = (pool, accept) => {
+    const clamped = [];
+    const clusters = ratioClusters(pool);
+    const distanceTo = (c) => Math.max(
+      c.ratios[0] - targets.farEyeRatio,
+      targets.farEyeRatio - c.ratios[1],
+      0
     );
-    if (!targets.defaulted.has("farEyeRatio")) {
-      return {
-        unreachable: true,
-        field: "farEyeRatio",
-        value: targets.farEyeRatio,
-        attainable: cluster.ratios
-      };
-    }
-    farEyeRatio = clampInto(farEyeRatio, cluster.ratios);
-    clamped.push("farEyeRatio");
-  }
-  const best = fitTurnRadius(ctx, cluster.candidates, farEyeRatio);
-  if (Math.abs(best.ratio - farEyeRatio) > TURN_DEPTH_EPS) {
-    if (!targets.defaulted.has("farEyeRatio")) {
-      return {
-        unreachable: true,
-        field: "farEyeRatio",
-        value: targets.farEyeRatio,
-        attainable: cluster.ratios
-      };
+    let farEyeRatio = targets.farEyeRatio;
+    let cluster = clusters.find((c) => runHolds(c, farEyeRatio));
+    if (cluster === void 0) {
+      cluster = clusters.reduce(
+        (a, b) => distanceTo(b) < distanceTo(a) ? b : a
+      );
+      if (!targets.defaulted.has("farEyeRatio")) {
+        return {
+          unreachable: true,
+          field: "farEyeRatio",
+          value: targets.farEyeRatio,
+          attainable: cluster.ratios
+        };
+      }
+      farEyeRatio = clampInto(farEyeRatio, cluster.ratios);
+      clamped.push("farEyeRatio");
+    }
+    const best = fitTurnRadius(ctx, cluster.candidates, farEyeRatio, accept);
+    if (Math.abs(best.ratio - farEyeRatio) > TURN_DEPTH_EPS) {
+      if (!targets.defaulted.has("farEyeRatio")) {
+        return {
+          unreachable: true,
+          field: "farEyeRatio",
+          value: targets.farEyeRatio,
+          attainable: cluster.ratios
+        };
+      }
+      if (!clamped.includes("farEyeRatio")) clamped.push("farEyeRatio");
+    }
+    if (!best.eye.reached) clamped.push("eyeShift");
+    if (best.silhouetteClamped) clamped.push("silhouetteRatio");
+    const eyeShift = (-best.eye.achieved + best.silhouetteCenterShift) / ctx.hh;
+    for (const [field, solution] of [
+      ["noseShift", best.nose],
+      ["mouthShift", best.mouth]
+    ]) {
+      if (solution.reached) continue;
+      if (!targets.defaulted.has(field)) {
+        return {
+          unreachable: true,
+          field,
+          value: targets[field],
+          // noseShift/mouthShift are MAGNITUDES too (see
+          // solveFeatureDepths), so a negative lower bound here would
+          // advertise a value the field's own contract already rules out; 0
+          // is the true floor.
+          attainable: [
+            Math.max(
+              0,
+              (-solution.attainable[1] + best.silhouetteCenterShift) / ctx.hh
+            ),
+            (-solution.attainable[0] + best.silhouetteCenterShift) / ctx.hh
+          ]
+        };
+      }
+      clamped.push(field);
     }
-    if (!clamped.includes("farEyeRatio")) clamped.push("farEyeRatio");
-  }
-  if (!best.eye.reached) clamped.push("eyeShift");
-  if (best.silhouetteClamped) clamped.push("silhouetteRatio");
-  const eyeShift = (-best.eye.achieved + best.silhouetteCenterShift) / ctx.hh;
-  for (const [field, solution] of [
-    ["noseShift", best.nose],
-    ["mouthShift", best.mouth]
-  ]) {
-    if (solution.reached) continue;
-    if (!targets.defaulted.has(field)) {
-      return {
-        unreachable: true,
-        field,
-        value: targets[field],
-        // noseShift/mouthShift are MAGNITUDES too (see solveFeatureDepths),
-        // so a negative lower bound here would advertise a value the field's
-        // own contract already rules out; 0 is the true floor.
-        attainable: [
-          Math.max(
-            0,
-            (-solution.attainable[1] + best.silhouetteCenterShift) / ctx.hh
-          ),
-          (-solution.attainable[0] + best.silhouetteCenterShift) / ctx.hh
-        ]
-      };
+    return {
+      unreachable: false,
+      radius: best.radius,
+      holdBase: best.holdBase,
+      holdEdgeAt: best.holdEdgeAt,
+      travel: best.travel,
+      surface: best.surface,
+      depths: {
+        eye: best.eye.depth,
+        nose: best.nose.depth,
+        mouth: best.mouth.depth
+      },
+      achieved: {
+        eyeShift,
+        farEyeRatio: best.ratio,
+        silhouetteRatio: best.renderedSilhouetteRatio
+      },
+      clamped,
+      ...best.strandOverlap === void 0 ? {} : { strandOverlap: best.strandOverlap }
+    };
+  };
+  const preferred = strandPreferredCandidates(
+    pass.candidates,
+    targets.farEyeRatio
+  );
+  if (preferred !== pass.candidates) {
+    const fitted = fitFrom(preferred, (c) => c.strandFeasible);
+    if (!fitted.unreachable && !fitted.clamped.includes("farEyeRatio")) {
+      return fitted;
     }
-    clamped.push(field);
   }
-  return {
-    unreachable: false,
-    radius: best.radius,
-    holdBase: best.holdBase,
-    holdEdgeAt: best.holdEdgeAt,
-    travel: best.travel,
-    surface: best.surface,
-    depths: {
-      eye: best.eye.depth,
-      nose: best.nose.depth,
-      mouth: best.mouth.depth
-    },
-    achieved: {
-      eyeShift,
-      farEyeRatio: best.ratio,
-      silhouetteRatio: best.renderedSilhouetteRatio
-    },
-    clamped
-  };
+  return fitFrom(pass.candidates, () => true);
 }
 var EYE_STACK_PREFIXES = ["eye_", "iris_", "pupil_", "highlight_"];
 var HAIR_FRONT_DEPTH = 0.1;
+var MOUTH_TURN_TILT_DEG = 5;
 var NOD_TRAVEL = 30;
 var NOD_BEND = 0.5;
 var HAIR_BACK_NOD_DEPTH = -0.135;
@@ -3521,10 +3892,16 @@ function turnSetup(layers) {
       )
     );
   }
+  const mouthAt = members.find((m) => m.role === "mouth").transform;
+  const mouthAnchor = {
+    x: mouthAt.x,
+    y: mouthAt.y,
+    tiltDeg: MOUTH_TURN_TILT_DEG
+  };
   const carriers = new Map(
     members.map((m) => [
       m.role,
-      { grid: groupGrids.get(m.group), part: m.part }
+      m.group === "mouthWarp" ? { grid: groupGrids.get(m.group), part: m.part, anchor: mouthAnchor } : { grid: groupGrids.get(m.group), part: m.part }
     ])
   );
   const maxShift = Math.max(turnShift.eye, turnShift.nose, turnShift.mouth);
@@ -3595,6 +3972,7 @@ function solveInputsOf(s) {
 }
 function generateIkiFromLayerSet(layers, canvas, options = {}) {
   validateLayerInputs(layers, canvas);
+  validateStrandEdges(layers, options.strandEdges);
   const hasHair = layers.some((l) => l.role === "hair_front");
   const bodyLayer = layers.find((l) => l.role === "body");
   const parameters = [...STANDARD_PARAMETERS];
@@ -3630,6 +4008,7 @@ function generateIkiFromLayerSet(layers, canvas, options = {}) {
     plateGuardRows,
     members,
     groupGrids,
+    carriers,
     parallaxUnitY,
     hasNose,
     hasMouthOpen
@@ -3638,7 +4017,8 @@ function generateIkiFromLayerSet(layers, canvas, options = {}) {
   const turn = hasNose ? solveTurnModel(
     resolveTurnTargets(options.turnTargets),
     ...solveInputsOf(setup),
-    options.headEdges
+    options.headEdges,
+    options.strandEdges
   ) : void 0;
   if (turn?.unreachable) {
     throw new TurnTargetError(
@@ -3656,7 +4036,8 @@ function generateIkiFromLayerSet(layers, canvas, options = {}) {
       holdBase: turn.holdBase,
       depths: turn.depths,
       achieved: turn.achieved,
-      clamped: turn.clamped
+      clamped: turn.clamped,
+      ...turn.strandOverlap === void 0 ? {} : { strandOverlap: turn.strandOverlap }
     });
   }
   const latticeReach = Math.max(
@@ -3729,7 +4110,8 @@ function generateIkiFromLayerSet(layers, canvas, options = {}) {
     }
   ];
   for (const [group, grid] of groupGrids) {
-    const family = turnFamily(members.find((m) => m.group === group).role);
+    const { role } = members.find((m) => m.group === group);
+    const family = turnFamily(role);
     const depth = group === "faceWarp" ? 0 : turn?.depths[family] ?? 0;
     deformers.push({
       kind: "warp",
@@ -3741,7 +4123,8 @@ function generateIkiFromLayerSet(layers, canvas, options = {}) {
         StandardParameter.AngleX,
         StandardParameter.AngleY,
         surface,
-        (deg) => depth * parallaxUnit * deg / HEAD_TURN_MAX_DEG
+        (deg) => depth * parallaxUnit * deg / HEAD_TURN_MAX_DEG,
+        carriers.get(role).anchor
       )
     });
   }