@ikijs/editor 0.12.0 → 0.12.2

package/README.md

@@ -1,5 +1,7 @@
 # @ikijs/editor
 
+> Part of [Iki](https://github.com/zeikar/iki), the open Live2D alternative that AI can build — free and MIT-licensed, with an open `.iki` format and a [Claude Code plugin](https://github.com/zeikar/iki/tree/main/plugin) that draws and rigs characters.
+
 **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.
 
@@ -66,10 +68,12 @@ not a reshaped face. The face plate translates, changing its width by a few
 percent, the chin leading it; the features lead the plate by their own amounts
 (the nose most, then the brows, eyes and mouth), the eyes foreshortening mildly
 about their own centres; the front hair rides the face where it lies over it and holds the head's
-outline where it draws it, and the back hair stays behind; the neck and the
+outline where it draws it — though on its cap the turn never carries its outer
+edge further outside the back hair painted behind it than the nod alone does —
+and the back hair stays behind; the neck and the
 ears the face layer paints are cut off into islands of the plate's own mesh,
 drawn behind the head — the neck stays (only the chin's shade slides across
-it), the ears lag the face. AngleZ rolls the head 10° about the chin; the torso only
+it), the ears lag the face, the far one narrowing. AngleZ rolls the head 10° about the chin; the torso only
 breathes.
 
 On a layer set with a `nose`, `options.turnTargets` — the cues a 30° reference
@@ -93,9 +97,11 @@ how much it covers at rest, and whether the bound held.
 An `eyeShift` you passed that runs past the room the art leaves the far eye —
 the face plate's edge, or the bangs' strand — is **clamped** and the rig is
 built, since that room is a fact about these layers, not about the reference;
-so is the profile's own turn where the art has less room than it needs. Every
-other target you passed that this layer set cannot reach **throws**, naming the
-field and the range it could have had: a `farEyeRatio` or `silhouetteRatio`
+so is the profile's own turn where the art has less room than it needs, and
+a `silhouetteRatio` that would narrow a plate drawn without hair too far for
+its head to cover the far ear's slide (see AUTO-RIG.md). Every other target
+you passed that this layer set cannot reach **throws**, naming the field and
+the range it could have had: a `farEyeRatio` or `silhouetteRatio`
 out of the rig's reach, or a `noseShift` / `mouthShift` outside what that
 feature can reach. Pass `options.onTurnSolved` to see what the turn settled on
 and which targets were clamped.

package/dist/index.d.mts

@@ -678,7 +678,10 @@ interface RigStyle {
      *  `hairFollow` rides it whole). Where back hair does, the edge rides
      *  further, as far as that back hair stays behind it through the turn and
      *  the nod, up to the front hair's follow there (`hairFollow`; over the
-     *  far eye's rows, as far as that eye's outer corner goes). */
+     *  far eye's rows, as far as that eye's outer corner goes). On the cap
+     *  (the rows above the eyes) the edge follows less where the turn would
+     *  otherwise carry it further outside its back hair than the nod alone
+     *  does. */
     outlineFollow?: number;
     /** How far the upper lid comes down, over the eye's height (0.30–0.67). */
     blink?: number;

package/dist/index.d.ts

@@ -678,7 +678,10 @@ interface RigStyle {
      *  `hairFollow` rides it whole). Where back hair does, the edge rides
      *  further, as far as that back hair stays behind it through the turn and
      *  the nod, up to the front hair's follow there (`hairFollow`; over the
-     *  far eye's rows, as far as that eye's outer corner goes). */
+     *  far eye's rows, as far as that eye's outer corner goes). On the cap
+     *  (the rows above the eyes) the edge follows less where the turn would
+     *  otherwise carry it further outside its back hair than the nod alone
+     *  does. */
     outlineFollow?: number;
     /** How far the upper lid comes down, over the eye's height (0.30–0.67). */
     blink?: number;

package/dist/index.js

@@ -2457,15 +2457,22 @@ var TURN = {
    *  where no back hair paints behind that edge. Where back hair does, the
    *  edge rides further, as far as that back hair stays behind it through
    *  the turn and the nod, up to the face's follow there (`hairFollow`;
-   *  over the far eye's rows, as far as that eye's outer corner goes). */
+   *  over the far eye's rows, as far as that eye's outer corner goes). On
+   *  the cap (the rows above the eyes) it follows less where the turn would
+   *  otherwise carry it further outside its back hair than the nod alone
+   *  does. */
   outlineFollow: 0,
   /** The back hair's slight counter-motion. */
   hairBack: -0.027,
-  /** The ears lag the plate: the far one moves this share of its slide, the
-   *  near one this at its widest reach, its root riding the head (the
-   *  samples' parallax ratios, 0.44 and 0.87). */
+  /** The ears lag the plate: the far one's outer edge moves this share of
+   *  its slide, the near one this at its widest reach, its root riding the
+   *  head (the samples' parallax ratios, 0.44 and 0.87). */
   earFar: 0.44,
-  earNear: 0.87
+  earNear: 0.87,
+  /** The far ear's width at full turn, about its outer edge, where the head
+   *  leaves it room (the samples' median: Haru 0.81 / 0.91, Hiyori 0.90 /
+   *  0.85, Mao 0.77 / 0.79; none fades); less where it does not. */
+  earFarScale: 0.83
 };
 var NOD = {
   faceTop: { up: -0.081, down: 0.178 },
@@ -2886,16 +2893,45 @@ function earField(m) {
     const s = Math.sign(ax);
     const a = Math.abs(ax) / 30;
     const dy = face(x, y, 0, ay)[1];
-    if (sideOf(m, x, s) === "far") return [s * a * TURN.earFar * m.face, dy];
     const d = Math.abs(x - f.axisX);
     const attach = ears.attachAt(y);
+    const span = Math.max(1, ears.outer - attach);
+    if (sideOf(m, x, s) === "far") {
+      const rim2 = TURN.earFar * m.face;
+      const root2 = earRoot(m, face, y, s);
+      const lead = Math.max(
+        0,
+        Math.min((1 - m.earFarScale) * span, root2 - rim2)
+      );
+      let along = rim2 + lead * (ears.outer - d) / span;
+      if (d < attach) along = Math.min(along, s * face(x, y, 30 * s, 0)[0]);
+      return [s * a * along, dy];
+    }
     if (d <= attach) return [face(x, y, ax, 0)[0], dy];
     const root = face(f.axisX + Math.sign(x - f.axisX) * attach, y, ax, 0)[0];
     const rim = s * a * TURN.earNear * m.face;
-    const t = Math.min(1, (d - attach) / Math.max(1, ears.outer - attach));
+    const t = Math.min(1, (d - attach) / span);
     return [root + (rim - root) * t, dy];
   };
 }
+function earRoot(m, face, y, s) {
+  const f = m.frame;
+  return s * face(f.axisX + s * f.ears.attachAt(y), y, 30 * s, 0)[0];
+}
+function farEarCovered(m) {
+  const ears = m.frame.ears;
+  if (ears === void 0) return true;
+  const face = faceField(m);
+  const rim = TURN.earFar * m.face;
+  const y0 = ears.bottom - 2;
+  const y1 = ears.top + 2;
+  const n = Math.max(1, Math.ceil(y1 - y0));
+  for (let i = 0; i <= n; i++) {
+    const y = y0 + (y1 - y0) * i / n;
+    for (const s of [-1, 1]) if (earRoot(m, face, y, s) < rim) return false;
+  }
+  return true;
+}
 function chinSlide(m) {
   const f = m.frame;
   return Math.abs(faceField(m)(f.axisX, f.chinY, 30, 0)[0]);
@@ -3038,14 +3074,19 @@ function hairFrontField(m) {
     );
     return core + (m.hairOuter - core) * out;
   };
-  const ride = outerRide(m, inner, coreAt, followAt);
-  const followOf = (x, y, s) => followAt(x, y, s) + (ride === void 0 ? 0 : ride(x, y, s));
+  const ride = outerRide(m, inner, coreAt, followAt, eyeY + 1.5 * eyeH);
+  const followOf = (x, y, s) => followAt(x, y, s) + (ride === void 0 ? 0 : ride.lift(x, y, s));
   const drift = Math.abs(m.hairBack);
   const crown = crownRide(m, cap, (x, y, s) => followOf(x, y, s) + drift);
+  const boundOf = (x, y, s) => {
+    if (ride === void 0) return followOf(x, y, s);
+    const b = ride.blend(y, s);
+    return (1 - b) * (followOf(x, y, s) + ride.cut(x, y, s)) - b * drift;
+  };
   return (x, y, ax, ay) => {
     const s = Math.sign(ax);
     const a = Math.abs(ax) / 30;
-    const rx = s * a * followOf(x, y, s) + a * (m.shellScale - 1) * (x - f.axisX);
+    const rx = s * a * boundOf(x, y, s) + a * (m.shellScale - 1) * (x - f.axisX);
     const ry = nodDy(NOD.hairFront, ay, f.hh);
     const bx = back(x, y, ax, ay)[0];
     const by = nodDy(cap, ay, f.hh);
@@ -3065,6 +3106,18 @@ function gridRow(ys, y, snap = false) {
   const r = Math.min(n - 2, Math.floor(v));
   return { r, t: v - r };
 }
+function gridCol(xs, x) {
+  let c = 0;
+  while (c < xs.length - 2 && xs[c + 1] < x) c++;
+  return { c, t: clamp((x - xs[c]) / (xs[c + 1] - xs[c]), 0, 1) };
+}
+function rowWindow(ys, r, limit) {
+  const n = ys.length;
+  return [
+    Math.max(0, Math.floor(ys[0] - ys[Math.max(0, r - 1)])),
+    Math.min(limit, Math.ceil(ys[0] - ys[Math.min(n - 1, r + 1)]))
+  ];
+}
 function renderedCrownBlend(m, ys) {
   const wr = ys.map((y) => crownBlend(m, y));
   return {
@@ -3140,10 +3193,11 @@ function paints(runs, px) {
   }
   return false;
 }
-function outerRide(m, inner, coreAt, followAt) {
+function outerRide(m, inner, coreAt, followAt, capLimit) {
   const f = m.frame;
-  const ys = m.hairFrontGrid?.ys;
-  if (ys === void 0) return void 0;
+  const grid = m.hairFrontGrid;
+  if (grid === void 0) return void 0;
+  const { xs, ys } = grid;
   const top = ys[0];
   if (f.hairRuns("hair_front", top) === void 0 || f.hairRuns("hair_back", top) === void 0) {
     return void 0;
@@ -3152,6 +3206,9 @@ function outerRide(m, inner, coreAt, followAt) {
   const sides = [-1, 1];
   const n = ys.length;
   const count = Math.round(top - ys[n - 1]);
+  let last = 0;
+  while (last + 1 < n && ys[last + 1] >= capLimit) last++;
+  const capRows = last === 0 ? 0 : Math.min(count, Math.floor(top - ys[last] - 0.5) + 1);
   const below = (NOD.hairFront.down - NOD.hairBack.down) * f.hh;
   const above = (NOD.hairBack.up - NOD.hairFront.up) * f.hh;
   const j0 = Math.floor(-above);
@@ -3160,8 +3217,9 @@ function outerRide(m, inner, coreAt, followAt) {
     (_, j) => f.hairRuns("hair_back", top - (j + j0) - 0.5)
   );
   const offset = sides.map(() => new Float64Array(count).fill(NaN));
-  const far = sides.map(() => new Float64Array(count));
-  const near = sides.map(() => new Float64Array(count));
+  const reachOut = sides.map(() => new Float64Array(count));
+  const reachIn = sides.map(() => new Float64Array(count));
+  const bound = sides.map(() => new Uint8Array(count));
   for (let i = 0; i < count; i++) {
     const y = top - i - 0.5;
     const front = f.hairRuns("hair_front", y);
@@ -3176,24 +3234,25 @@ function outerRide(m, inner, coreAt, followAt) {
         inward = Math.min(inward, c.inward);
       }
       offset[k][i] = side * (edge - f.axisX);
-      far[k][i] = m.shellScale * outward - drift;
-      near[k][i] = m.shellScale * inward - drift;
+      reachOut[k][i] = outward;
+      reachIn[k][i] = inward;
+      if (i < capRows && runReach(backRows[i - j0], edge, side).inward > 0)
+        bound[k][i] = 1;
     });
   }
   const end = new Float64Array(n * 2);
   const lift = new Float64Array(n * 4);
   for (let r = 0; r < n; r++) {
-    const i0 = Math.max(0, Math.floor(top - ys[Math.max(0, r - 1)]));
-    const i1 = Math.min(count, Math.ceil(top - ys[Math.min(n - 1, r + 1)]));
+    const [i0, i1] = rowWindow(ys, r, count);
     sides.forEach((side, k) => {
       let d = Infinity;
-      let allowFar = Infinity;
-      let allowNear = Infinity;
+      let outward = Infinity;
+      let inward = Infinity;
       for (let i = i0; i < i1; i++) {
         if (Number.isNaN(offset[k][i])) continue;
         d = Math.min(d, offset[k][i]);
-        allowFar = Math.min(allowFar, far[k][i]);
-        allowNear = Math.min(allowNear, near[k][i]);
+        outward = Math.min(outward, reachOut[k][i]);
+        inward = Math.min(inward, reachIn[k][i]);
       }
       end[r * 2 + k] = d;
       if (d === Infinity || d <= inner) return;
@@ -3201,7 +3260,7 @@ function outerRide(m, inner, coreAt, followAt) {
       sides.forEach((s, j) => {
         const allow = Math.min(
           coreAt(x, ys[r], s),
-          s === side ? allowFar : allowNear
+          m.shellScale * (s === side ? outward : inward) - drift
         );
         lift[(r * 2 + k) * 2 + j] = Math.max(0, allow - followAt(x, ys[r], s));
       });
@@ -3211,7 +3270,7 @@ function outerRide(m, inner, coreAt, followAt) {
     const v = lift[(r * 2 + k) * 2 + j];
     return v === 0 ? 0 : v * Math.min(1, (d - inner) / (end[r * 2 + k] - inner));
   };
-  return (x, y, s) => {
+  const liftAt = (x, y, s) => {
     const d = Math.abs(x - f.axisX);
     if (s === 0 || d <= inner) return 0;
     const k = x < f.axisX ? 0 : 1;
@@ -3219,6 +3278,130 @@ function outerRide(m, inner, coreAt, followAt) {
     const { r, t } = gridRow(ys, y, true);
     return rowRide(r, k, j, d) * (1 - t) + rowRide(r + 1, k, j, d) * t;
   };
+  const nc = xs.length;
+  const along = (v, x) => {
+    const { c, t } = gridCol(xs, x);
+    return v[c] + (v[c + 1] - v[c]) * t;
+  };
+  const readAt = (r, x, y) => {
+    const { c, t: fx } = gridCol(xs, x);
+    const dx = xs[c + 1] - xs[c];
+    if (r + 1 < n && y <= ys[r] && y >= ys[r + 1]) {
+      const fy = (ys[r] - y) / (ys[r] - ys[r + 1]);
+      if (fy >= 1) return void 0;
+      return fx <= fy ? xs[c] : xs[c] + (fx - fy) / (1 - fy) * dx;
+    }
+    if (r > 0 && y > ys[r] && y < ys[r - 1]) {
+      const fy = (ys[r - 1] - y) / (ys[r - 1] - ys[r]);
+      return fx <= fy ? xs[c] + fx / fy * dx : xs[c + 1];
+    }
+    return void 0;
+  };
+  const ahead = (e, s) => s === e.side ? e.outward : e.inward;
+  const behind = (e, s) => s === e.side ? e.inward : e.outward;
+  const capCut = (r, s, side, today, mine) => {
+    const reach = Math.max(...mine.map((e) => side * (e.x - f.axisX)));
+    const quarter = new Float64Array(nc);
+    const cols = xs.map((_, c) => c).filter((c) => (xs[c] < f.axisX ? -1 : 1) === side);
+    if (side < 0) cols.reverse();
+    let total = 0;
+    let x0 = f.axisX;
+    let d0 = s * followAt(f.axisX, ys[r], s);
+    let open = true;
+    for (const c of cols) {
+      if (open) {
+        const d = (m.shellScale - 1) * (xs[c] - f.axisX) + s * today[c];
+        const rest = side * (xs[c] - x0);
+        const full = rest + side * (d - d0);
+        total += Math.max(0, Math.min(full, rest)) / 4;
+        x0 = xs[c];
+        d0 = d;
+        open = side * (xs[c] - f.axisX) < reach;
+      }
+      quarter[c] = total;
+    }
+    let scale = 0;
+    for (const e of mine) {
+      const need = along(today, e.at) - (m.shellScale * ahead(e, s) - drift);
+      if (need <= 0) continue;
+      const q = along(quarter, e.at);
+      scale = Math.max(scale, q > 0 ? need / q : 1);
+    }
+    scale = Math.min(1, scale);
+    return quarter.map((q) => scale * q);
+  };
+  const cuts = new Float64Array(n * 2 * nc);
+  const blend = new Float64Array(n * 2);
+  const wr = ys.map((y) => crownBlend(m, y));
+  for (let r = 0; r <= last && capRows > 0; r++) {
+    const w = wr[r];
+    if (w <= 0) continue;
+    const edges = [];
+    const [i0, i1] = rowWindow(ys, r, capRows);
+    for (let i = i0; i < i1; i++) {
+      sides.forEach((side, k) => {
+        if (bound[k][i] === 0) return;
+        const x = f.axisX + side * offset[k][i];
+        const at = readAt(r, x, top - i - 0.5);
+        if (at === void 0) return;
+        edges.push({
+          side,
+          x,
+          at,
+          outward: reachOut[k][i],
+          inward: reachIn[k][i]
+        });
+      });
+    }
+    if (edges.length === 0) continue;
+    sides.forEach((s, j) => {
+      const today = xs.map((x) => followAt(x, ys[r], s) + liftAt(x, ys[r], s));
+      const after = today.slice();
+      if (w >= 1) {
+        for (const side of sides) {
+          const mine = edges.filter((e) => e.side === side);
+          if (mine.length === 0) continue;
+          const cut = capCut(r, s, side, today, mine);
+          for (let c = 0; c < nc; c++) after[c] -= cut[c];
+        }
+      }
+      let b = 0;
+      for (const e of edges) {
+        const rel = w * (along(after, e.at) + drift);
+        const hi = m.shellScale * ahead(e, s);
+        const lo = -m.shellScale * behind(e, s);
+        if (rel > hi) b = Math.max(b, 1 - hi / rel);
+        else if (rel < lo) b = Math.max(b, 1 - lo / rel);
+      }
+      blend[r * 2 + j] = b;
+      for (let c = 0; c < nc; c++)
+        cuts[(r * 2 + j) * nc + c] = after[c] - today[c];
+    });
+  }
+  for (let j = 0; j < 2; j++) {
+    for (let r = n - 2; r >= 0; r--) {
+      if (wr[r] < 1)
+        blend[r * 2 + j] = Math.max(blend[r * 2 + j], blend[(r + 1) * 2 + j]);
+    }
+  }
+  const cutRow = (r, j, x) => r > last ? 0 : along(cuts.subarray((r * 2 + j) * nc, (r * 2 + j + 1) * nc), x);
+  return {
+    lift: liftAt,
+    // Between vertex rows, as the render interpolates; a vertex reads its own
+    // row's alone.
+    cut: (x, y, s) => {
+      if (s === 0) return 0;
+      const j = s < 0 ? 0 : 1;
+      const { r, t } = gridRow(ys, y, true);
+      return cutRow(r, j, x) * (1 - t) + cutRow(r + 1, j, x) * t;
+    },
+    blend: (y, s) => {
+      if (s === 0) return 0;
+      const j = s < 0 ? 0 : 1;
+      const { r, t } = gridRow(ys, y, true);
+      return blend[r * 2 + j] * (1 - t) + blend[(r + 1) * 2 + j] * t;
+    }
+  };
 }
 function crownRide(m, cap, relAt) {
   const f = m.frame;
@@ -3258,8 +3441,7 @@ function crownRide(m, cap, relAt) {
     return rel[at];
   };
   const cellR = (x, y, k) => {
-    let c = 0;
-    while (c < xs.length - 2 && xs[c + 1] < x) c++;
+    const { c } = gridCol(xs, x);
     const { r } = gridRow(ys, y);
     return Math.max(
       relOf(r, c, k),
@@ -3349,8 +3531,7 @@ function crownRide(m, cap, relAt) {
     const out = wr.slice();
     for (let r = 0; r < n; r++) {
       if (wr[r] >= 1) continue;
-      const i0 = Math.max(0, Math.floor(top - ys[Math.max(0, r - 1)]));
-      const i1 = Math.min(count, Math.ceil(top - ys[Math.min(n - 1, r + 1)]));
+      const [i0, i1] = rowWindow(ys, r, count);
       let least = Infinity;
       for (let i = i0; i < i1; i++) least = Math.min(least, slackAt(i, k));
       out[r] = wr[r] + clamp(least, 0, 1 - wr[r]);
@@ -4019,6 +4200,18 @@ function fitTurn(ctx, targets, style, build) {
     }
     p.shell = bisect((k) => at(k) - s, SHELL_RANGE[0], SHELL_RANGE[1]);
   }
+  const covered = (shell) => farEarCovered(build({ ...p, shell }));
+  if (!covered(p.shell) && covered(Math.max(1, p.shell))) {
+    let lo = p.shell;
+    let hi = Math.max(1, p.shell);
+    for (let i = 0; i < 50; i++) {
+      const mid = (lo + hi) / 2;
+      if (covered(mid)) hi = mid;
+      else lo = mid;
+    }
+    p.shell = hi;
+    clamped.push("silhouetteRatio");
+  }
   const hb = ctx.restHalf;
   const feature = (key, family, at, box) => {
     const base = build(p);
@@ -4177,6 +4370,7 @@ function buildTurn(frame, landmarks, q) {
     hairOuter: q.outline * face,
     hairBack: A * hh * TURN.hairBack,
     shellScale: q.shell,
+    earFarScale: 1 + A * (TURN.earFarScale - 1),
     ...landmarks
   };
 }