@ikijs/editor 0.24.1 → 0.25.0

package/dist/index.js

@@ -36,6 +36,8 @@ __export(index_exports, {
   LIP_INSIDE_ROLES: () => LIP_INSIDE_ROLES,
   LIP_ROLES: () => LIP_ROLES,
   LayerGeometryError: () => LayerGeometryError,
+  PatchError: () => PatchError,
+  SHUT_BY: () => SHUT_BY,
   SPECK_CORE_FRACTION: () => SPECK_CORE_FRACTION,
   SetDeformerBindings: () => SetDeformerBindings,
   SetDeformerParent: () => SetDeformerParent,
@@ -1560,8 +1562,8 @@ function foregroundSpan(mask, width, height, rowLo, rowHi) {
   }
   return { left, right };
 }
-function headHalfOf(span) {
-  return (span.right - span.left + 1) / 2;
+function headHalfOf(span2) {
+  return (span2.right - span2.left + 1) / 2;
 }
 var DARK_SHARE = 0.55;
 function jawRowsOf(rgba, canvasW, bbox, rowLeft, rowRight) {
@@ -1571,9 +1573,9 @@ function jawRowsOf(rgba, canvasW, bbox, rowLeft, rowRight) {
   let widest = bbox.y;
   let widestSpan = -1;
   for (let y = bbox.y; y < bbox.y + bbox.h; y++) {
-    const span = rowRight[y] - rowLeft[y];
-    if (span >= widestSpan) {
-      widestSpan = span;
+    const span2 = rowRight[y] - rowLeft[y];
+    if (span2 >= widestSpan) {
+      widestSpan = span2;
       widest = y;
     }
     for (let x = bbox.x; x < bbox.x + bbox.w; x++) {
@@ -1742,14 +1744,14 @@ function createLayerSetMeasurer(canvas) {
   }
   function finish() {
     const eyeRow = eyeBandRowOf(layerInputs);
-    const span = foregroundSpan(
+    const span2 = foregroundSpan(
       opaque,
       canvasW,
       canvasH,
       eyeRow - HEAD_BAND,
       eyeRow + HEAD_BAND
     );
-    const headHalfWidth = span.right > span.left ? headHalfOf(span) : void 0;
+    const headHalfWidth = span2.right > span2.left ? headHalfOf(span2) : void 0;
     const headHalfWidthApplied = headHalfWidth !== void 0 && headHalfWidth > facePlateHalfOf(layerInputs);
     let headEdges;
     if (headHalfWidthApplied) {
@@ -1777,9 +1779,9 @@ function createLayerSetMeasurer(canvas) {
         const centre = iris.bbox.x + iris.bbox.w / 2;
         const otherX = other.bbox.x + other.bbox.w / 2 - half;
         const c = side < 0 ? Math.ceil(centre) - 1 : Math.floor(centre);
-        const span2 = rowSpansByRole.find((s) => s.role === iris.role);
-        if (span2.rowRight[r] < span2.rowLeft[r]) return void 0;
-        const minRun = STRAND_MIN_RUN_FRACTION * (span2.rowRight[r] + 1 - span2.rowLeft[r]);
+        const span3 = rowSpansByRole.find((s) => s.role === iris.role);
+        if (span3.rowRight[r] < span3.rowLeft[r]) return void 0;
+        const minRun = STRAND_MIN_RUN_FRACTION * (span3.rowRight[r] + 1 - span3.rowLeft[r]);
         const strand = new Uint8Array(canvasW);
         const runs = r >= hairTop && r < hairTop + hairRuns.length ? hairRuns[r - hairTop] : [];
         for (let k = 0; k < runs.length; k += 2) {
@@ -1804,8 +1806,8 @@ function createLayerSetMeasurer(canvas) {
         while (strandAt(x)) x += side;
         return {
           y: canvasH / 2 - (r + 0.5),
-          irisOuter: (side < 0 ? span2.rowLeft[r] : span2.rowRight[r] + 1) - half,
-          irisInner: (side < 0 ? span2.rowRight[r] + 1 : span2.rowLeft[r]) - half,
+          irisOuter: (side < 0 ? span3.rowLeft[r] : span3.rowRight[r] + 1) - half,
+          irisInner: (side < 0 ? span3.rowRight[r] + 1 : span3.rowLeft[r]) - half,
           runOuter: outerBoundary(x - side),
           runFace
         };
@@ -2209,6 +2211,12 @@ var DEFAULT_TURN_TARGETS = Object.freeze({
   farEyeRatio: round2(TURN.eyeFarScale / TURN.eyeNearScale),
   silhouetteRatio: 1
 });
+var PatchError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PatchError";
+  }
+};
 
 // src/auto-rig/arms.ts
 var import_format5 = require("@ikijs/format");
@@ -2834,7 +2842,7 @@ var ARM_IDS = {
 };
 function endPivot(layer, end) {
   const { bbox, canvasW, canvasH, rowRuns } = layer;
-  const span = runSpan(layer);
+  const span2 = runSpan(layer);
   const from = (k) => end === "top" ? k : bbox.h - 1 - k;
   const painted = rowRuns?.flatMap((runs, k) => runs.length > 0 ? [k] : []) ?? [];
   const firstK = end === "top" ? painted[0] ?? 0 : painted.at(-1) ?? bbox.h - 1;
@@ -2842,13 +2850,13 @@ function endPivot(layer, end) {
   const hi = Math.max(lo, Math.floor(CAP_ROWS[1] * bbox.h));
   const widths = [];
   for (let k = lo; k <= hi; k++) {
-    const [s2, e2] = span(from(k));
+    const [s2, e2] = span2(from(k));
     widths.push(e2 - s2);
   }
   widths.sort((p, q) => p - q);
   const radius = widths[widths.length >> 1] / 2;
   const ks = end === "top" ? firstK + radius : firstK - radius;
-  const [s, e] = span(Math.round(ks));
+  const [s, e] = span2(Math.round(ks));
   return {
     point: {
       x: roundTo((s + e) / 2 - canvasW / 2, 0.01),
@@ -2873,9 +2881,9 @@ function runSpan(layer) {
 function armGeometry(layer, bodyAxisX) {
   const { bbox, canvasW, canvasH, rowRuns } = layer;
   const b = boxOfLayer(layer);
-  const span = runSpan(layer);
+  const span2 = runSpan(layer);
   const centreX = (k) => {
-    const [s2, e2] = span(k);
+    const [s2, e2] = span2(k);
     return (s2 + e2) / 2 - canvasW / 2;
   };
   const rowY = (k) => canvasH / 2 - (bbox.y + k + 0.5);
@@ -2889,7 +2897,7 @@ function armGeometry(layer, bodyAxisX) {
     );
   }
   const elbow = { x: roundTo(centreX(ke), 0.01), y: roundTo(rowY(ke), 0.01) };
-  const [s, e] = span(ke);
+  const [s, e] = span2(ke);
   const capRadius = Math.min(
     (e - s) / 2 + 1,
     elbow.x - b.x0,
@@ -2899,7 +2907,7 @@ function armGeometry(layer, bodyAxisX) {
   const inside = (x, y) => {
     const k = Math.floor(y) - bbox.y;
     if (k < 0 || k >= bbox.h) return false;
-    const [rs, re] = span(k);
+    const [rs, re] = span2(k);
     return rs < x && x < re;
   };
   const capRays = Array.from({ length: CAP_SEGMENTS + 1 }, (_, i) => {
@@ -3106,13 +3114,24 @@ function forearmPoseDeformer(role, arm) {
 }
 
 // src/auto-rig/mouth.ts
-var import_format7 = require("@ikijs/format");
+var import_format8 = require("@ikijs/format");
 
 // src/auto-rig/roles.ts
+var import_format7 = 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_format7.StandardParameter.EyeOpenLeft],
+  ["lash_lower_L", import_format7.StandardParameter.EyeOpenLeft],
+  ["eye_R", import_format7.StandardParameter.EyeOpenRight],
+  ["lash_lower_R", import_format7.StandardParameter.EyeOpenRight],
+  ...[...LIP_ROLES, ...LIP_INSIDE_ROLES].map((id) => [
+    id,
+    import_format7.StandardParameter.MouthOpen
+  ])
+]);
 var ROLE_TABLE = [
   { role: "hair_back", family: "hair_back" },
   { role: "body", family: "body" },
@@ -3457,7 +3476,7 @@ function columnOfKnot(knot, opening) {
 function mouthFoldWarp(role, mesh, xs, box, opening) {
   const fold = mouthFold(role, opening);
   return localWarp(
-    import_format7.StandardParameter.MouthOpen,
+    import_format8.StandardParameter.MouthOpen,
     mesh,
     box,
     [0, 1],
@@ -3466,13 +3485,13 @@ function mouthFoldWarp(role, mesh, xs, box, opening) {
 }
 function mouthRestShift(byRole) {
   const rig = buildMouthRig(byRole);
-  const fields = /* @__PURE__ */ new Map();
+  const fields2 = /* @__PURE__ */ new Map();
   for (const role of ["lip_upper", "lip_lower"]) {
     const box = boxOfLayer(byRole.get(role));
     const { mesh, xs } = mouthMesh(box, rig.knots);
     const warp = mouthFoldWarp(role, mesh, xs, box, rig.opening);
     const offsets = warp.keyforms[0].offsets;
-    fields.set(role, {
+    fields2.set(role, {
       box,
       xs,
       rows: offsets.length / 2 / xs.length - 1,
@@ -3481,7 +3500,7 @@ function mouthRestShift(byRole) {
   }
   const { canvasW, canvasH } = byRole.get("lip_upper");
   return (role, col, row) => {
-    const { box, xs, rows, dy } = fields.get(role);
+    const { box, xs, rows, dy } = fields2.get(role);
     const x = col + 0.5 - canvasW / 2;
     const y = canvasH / 2 - (row + 0.5);
     if (x < box.x0 || x > box.x1 || y < box.y0 || y > box.y1) return void 0;
@@ -3570,32 +3589,32 @@ function mouthAnchor(byRole) {
 }
 
 // src/auto-rig/generate.ts
-var import_format10 = require("@ikijs/format");
+var import_format12 = require("@ikijs/format");
 
 // src/auto-rig/animations.ts
-var import_format8 = require("@ikijs/format");
+var import_format9 = require("@ikijs/format");
 function browsY(y) {
   return [
-    { parameter: import_format8.StandardParameter.BrowLeftY, value: y, blend: "add" },
-    { parameter: import_format8.StandardParameter.BrowRightY, value: y, blend: "add" }
+    { parameter: import_format9.StandardParameter.BrowLeftY, value: y, blend: "add" },
+    { parameter: import_format9.StandardParameter.BrowRightY, value: y, blend: "add" }
   ];
 }
 function browsTilt(innerDown) {
   return [
-    { parameter: import_format8.StandardParameter.BrowLeftAngle, value: innerDown, blend: "add" },
-    { parameter: import_format8.StandardParameter.BrowRightAngle, value: -innerDown, blend: "add" }
+    { parameter: import_format9.StandardParameter.BrowLeftAngle, value: innerDown, blend: "add" },
+    { parameter: import_format9.StandardParameter.BrowRightAngle, value: -innerDown, blend: "add" }
   ];
 }
 function cheek(value) {
-  return { parameter: import_format8.StandardParameter.Cheek, value, blend: "add" };
+  return { parameter: import_format9.StandardParameter.Cheek, value, blend: "add" };
 }
-var BROWS = [import_format8.StandardParameter.BrowLeftY, import_format8.StandardParameter.BrowRightY, import_format8.StandardParameter.BrowLeftAngle, import_format8.StandardParameter.BrowRightAngle];
+var BROWS = [import_format9.StandardParameter.BrowLeftY, import_format9.StandardParameter.BrowRightY, import_format9.StandardParameter.BrowLeftAngle, import_format9.StandardParameter.BrowRightAngle];
 var EXPRESSIONS = [
   {
     id: "smile",
     description: "Smiling and pleased: warm, friendly, content. For greetings, thanks, agreement and gentle happiness.",
     parameters: [
-      { parameter: import_format8.StandardParameter.MouthForm, value: 1, blend: "add" },
+      { parameter: import_format9.StandardParameter.MouthForm, value: 1, blend: "add" },
       ...browsY(0.25),
       cheek(0.4)
     ]
@@ -3604,10 +3623,10 @@ var EXPRESSIONS = [
     id: "laugh",
     description: "Laughing, eyes shut and mouth open: delighted, amused. For jokes, playfulness and big joy.",
     parameters: [
-      { parameter: import_format8.StandardParameter.EyeOpenLeft, value: 0, blend: "multiply" },
-      { parameter: import_format8.StandardParameter.EyeOpenRight, value: 0, blend: "multiply" },
-      { parameter: import_format8.StandardParameter.MouthForm, value: 1, blend: "add" },
-      { parameter: import_format8.StandardParameter.MouthOpen, value: 0.8, blend: "overwrite" },
+      { parameter: import_format9.StandardParameter.EyeOpenLeft, value: 0, blend: "multiply" },
+      { parameter: import_format9.StandardParameter.EyeOpenRight, value: 0, blend: "multiply" },
+      { parameter: import_format9.StandardParameter.MouthForm, value: 1, blend: "add" },
+      { parameter: import_format9.StandardParameter.MouthOpen, value: 0.8, blend: "overwrite" },
       ...browsY(0.4),
       cheek(0.65)
     ]
@@ -3619,7 +3638,7 @@ var EXPRESSIONS = [
     parameters: [
       ...browsY(-0.5),
       ...browsTilt(0.8),
-      { parameter: import_format8.StandardParameter.MouthForm, value: -0.9, blend: "add" }
+      { parameter: import_format9.StandardParameter.MouthForm, value: -0.9, blend: "add" }
     ]
   },
   {
@@ -3629,7 +3648,7 @@ var EXPRESSIONS = [
     parameters: [
       ...browsY(0.35),
       ...browsTilt(-0.8),
-      { parameter: import_format8.StandardParameter.MouthForm, value: -0.8, blend: "add" }
+      { parameter: import_format9.StandardParameter.MouthForm, value: -0.8, blend: "add" }
     ]
   },
   {
@@ -3637,18 +3656,18 @@ var EXPRESSIONS = [
     description: "Surprised, mouth dropped open: startled, amazed. For shock, sudden news or disbelief.",
     parameters: [
       ...browsY(0.8),
-      { parameter: import_format8.StandardParameter.MouthOpen, value: 0.9, blend: "overwrite" }
+      { parameter: import_format9.StandardParameter.MouthOpen, value: 0.9, blend: "overwrite" }
     ]
   },
   {
     id: "shy",
     description: "Shy or embarrassed: bashful, flustered. For being praised, teased or caught off guard.",
-    needs: [import_format8.StandardParameter.Cheek],
+    needs: [import_format9.StandardParameter.Cheek],
     parameters: [
       cheek(1),
       // Gaze down.
-      { parameter: import_format8.StandardParameter.EyeballY, value: -0.65, blend: "add" },
-      { parameter: import_format8.StandardParameter.MouthForm, value: 0.4, blend: "add" },
+      { parameter: import_format9.StandardParameter.EyeballY, value: -0.65, blend: "add" },
+      { parameter: import_format9.StandardParameter.MouthForm, value: 0.4, blend: "add" },
       ...browsTilt(-0.25)
     ]
   }
@@ -3668,7 +3687,7 @@ var HEAD_MOTIONS = {
       duration: 1,
       curves: [
         {
-          parameter: import_format8.StandardParameter.AngleY,
+          parameter: import_format9.StandardParameter.AngleY,
           keys: [
             [0, 0],
             [0.3, -18],
@@ -3689,7 +3708,7 @@ var HEAD_MOTIONS = {
       fadeIn: 0.15,
       curves: [
         {
-          parameter: import_format8.StandardParameter.AngleX,
+          parameter: import_format9.StandardParameter.AngleX,
           keys: [
             [0, 0],
             [0.2, -18],
@@ -3708,7 +3727,7 @@ var HEAD_MOTIONS = {
       duration: 1.4,
       curves: [
         {
-          parameter: import_format8.StandardParameter.AngleZ,
+          parameter: import_format9.StandardParameter.AngleZ,
           keys: [
             [0, 0],
             [0.35, 20],
@@ -3729,7 +3748,7 @@ var WAVE = {
       fadeOut: 0.15,
       curves: [
         {
-          parameter: import_format8.StandardParameter.ArmPoseRight,
+          parameter: import_format9.StandardParameter.ArmPoseRight,
           interpolation: "linear",
           keys: [
             [0, 0],
@@ -3739,7 +3758,7 @@ var WAVE = {
           ]
         },
         {
-          parameter: import_format8.StandardParameter.ArmRight,
+          parameter: import_format9.StandardParameter.ArmRight,
           keys: [
             [0, 0],
             [0.4, 10],
@@ -3748,7 +3767,7 @@ var WAVE = {
           ]
         },
         {
-          parameter: import_format8.StandardParameter.ArmPoseAngleRight,
+          parameter: import_format9.StandardParameter.ArmPoseAngleRight,
           keys: [
             [0, 0],
             [0.5, 0],
@@ -3764,7 +3783,7 @@ var WAVE = {
   ]
 };
 function defaultMotions(declared) {
-  const waves = [import_format8.StandardParameter.ArmRight, import_format8.StandardParameter.ArmPoseRight, import_format8.StandardParameter.ArmPoseAngleRight].every(
+  const waves = [import_format9.StandardParameter.ArmRight, import_format9.StandardParameter.ArmPoseRight, import_format9.StandardParameter.ArmPoseAngleRight].every(
     (id) => declared.has(id)
   );
   return waves ? { ...HEAD_MOTIONS, ...WAVE } : HEAD_MOTIONS;
@@ -4000,7 +4019,7 @@ function checkStrandEdges(strand, irises, hair) {
 }
 
 // src/auto-rig/context.ts
-var import_format9 = require("@ikijs/format");
+var import_format10 = require("@ikijs/format");
 
 // src/auto-rig/head.ts
 function outerEdge(runs, axisX, side) {
@@ -4109,14 +4128,14 @@ function buildHeadFrame(layers, opts) {
     const rawRows = raw;
     const earless = (chin) => {
       const rowOf = (y) => Math.round(canvasH / 2 - y - faceLayer.bbox.y - 0.5);
-      const span = Math.max(1, eyeY - chin);
+      const span2 = Math.max(1, eyeY - chin);
       const found = findEars(
         rawRows,
         wMax,
         Math.round(0.2 * rawRows.length),
         Math.min(rawRows.length - 1, rowOf(chin)),
-        Math.round(0.1 * span),
-        Math.round(0.8 * span)
+        Math.round(0.1 * span2),
+        Math.round(0.8 * span2)
       );
       if (found === void 0) return profile;
       const { top, bottom } = found;
@@ -4150,16 +4169,16 @@ function buildHeadFrame(layers, opts) {
         }
       }
       if (neckRow >= 0 && n - neckRow >= 0.12 * n) {
-        let span = 0;
+        let span2 = 0;
         let waist = Infinity;
         for (let r = neckRow; r < n; r++) {
-          span = Math.max(span, profile[r]);
+          span2 = Math.max(span2, profile[r]);
           if (r < n - tail) waist = Math.min(waist, profile[r]);
         }
         neck = {
           topY: rowY(neckRow),
           half: profile[neckRow],
-          span,
+          span: span2,
           waist: Math.min(waist, profile[neckRow])
         };
       }
@@ -4359,22 +4378,22 @@ function earField(m) {
     const dy = face(x, y, 0, ay)[1];
     const d = Math.abs(x - f.axisX);
     const attach = ears.attachAt(y);
-    const span = Math.max(1, ears.outer - attach);
+    const span2 = 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)
+        Math.min((1 - m.earFarScale) * span2, root2 - rim2)
       );
-      let along = rim2 + lead * (ears.outer - d) / span;
+      let along = rim2 + lead * (ears.outer - d) / span2;
       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) / span);
+    const t = Math.min(1, (d - attach) / span2);
     return [root + (rim - root) * t, dy];
   };
 }
@@ -5130,7 +5149,7 @@ function renderedLander(turn, parts, grids, from = /* @__PURE__ */ new Map()) {
     const family = roleSpec(role).family;
     const part = parts.find((p) => p.id === role);
     const g = grids.get(family);
-    const warp = part?.warps?.find((w) => w.parameter === import_format9.StandardParameter.AngleX);
+    const warp = part?.warps?.find((w) => w.parameter === import_format10.StandardParameter.AngleX);
     if (part === void 0 || part.mesh === void 0 || !g && !warp) {
       return x + field(role)(x, y, ax, 0)[0];
     }
@@ -5269,11 +5288,11 @@ function buildFaceMesh(frame, b, head, neckCells) {
   const indices = [];
   const neck = frame.neck;
   if (neck !== void 0) {
-    const span = neck.span + pad;
-    const nc = cellsFor(2 * span, neckCells.px, neckCells.min, neckCells.max);
+    const span2 = neck.span + pad;
+    const nc = cellsFor(2 * span2, neckCells.px, neckCells.min, neckCells.max);
     const xs2 = columns(
-      Math.max(b.x0, frame.axisX - span),
-      Math.min(b.x1, frame.axisX + span),
+      Math.max(b.x0, frame.axisX - span2),
+      Math.min(b.x1, frame.axisX + span2),
       nc
     );
     const sampleBelow = (x) => Math.max(
@@ -5409,6 +5428,9 @@ function buildFaceMesh(frame, b, head, neckCells) {
   return { mesh: { vertices, uvs, indices }, region, headStart };
 }
 
+// src/auto-rig/patches.ts
+var import_format11 = require("@ikijs/format");
+
 // src/auto-rig/solve.ts
 var RANGES = {
   // [lo, hi, lo exclusive]
@@ -5839,6 +5861,235 @@ function buildTurn(frame, landmarks, q) {
   };
 }
 
+// src/auto-rig/patches.ts
+var OP_KEYS = ["target", "at", "region", "by", "falloff", "why"];
+var REGION_KEYS = ["role", "x", "y"];
+var BY_KEYS = ["dx", "dy"];
+var ROLLS = /* @__PURE__ */ new Set([import_format11.StandardParameter.AngleZ, import_format11.StandardParameter.BodyAngleZ]);
+var REST_IS_ART = "rest is the drawn art, which no patch changes (change it with the layout or by regenerating the layer)";
+function applyPatches(patches, ctx) {
+  if (!Array.isArray(patches)) {
+    throw new PatchError(
+      `patches must be an array, got ${patches === null ? "null" : typeof patches}`
+    );
+  }
+  const sums = /* @__PURE__ */ new Map();
+  const reports = patches.map((op, i) => replay(op, i, ctx, sums));
+  for (const [offsets, s] of sums) {
+    s.terms.forEach((t, k) => {
+      if (t.length === 0) return;
+      const d = t.sort((a, b) => a - b).reduce((a, b) => a + b, 0);
+      offsets[k] = roundTo(offsets[k] + d / s.scale[k % 2], s.step);
+    });
+  }
+  return reports;
+}
+function replay(op, i, ctx, sums) {
+  const name = `patches[${i}]`;
+  const o = fields(name, op, OP_KEYS);
+  const target = text(`${name}.target`, o.target);
+  const at = numbers(`${name}.at`, o.at);
+  const region = fields(`${name}.region`, o.region, REGION_KEYS);
+  const role = text(`${name}.region.role`, region.role);
+  const x = span(`${name}.region.x`, region.x);
+  const y = span(`${name}.region.y`, region.y);
+  const by = fields(`${name}.by`, o.by, BY_KEYS);
+  const dx = finite2(`${name}.by.dx`, by.dx);
+  const dy = finite2(`${name}.by.dy`, by.dy);
+  const falloff = o.falloff === void 0 ? 0 : finite2(`${name}.falloff`, o.falloff, 0);
+  if (o.why !== void 0) text(`${name}.why`, o.why);
+  const box = ctx.boxOf(role);
+  if (box === void 0) {
+    const roles = [...new Set(ctx.parts.map((p) => roleOfPart(p.id)))].filter(
+      (r) => ctx.boxOf(r) !== void 0
+    );
+    throw new PatchError(
+      `${name}.region.role "${role}" is not a layer of this set (roles: ${roles.join(", ")})`
+    );
+  }
+  const stop = resolveStop(name, target, at, ctx);
+  const { points } = stop;
+  const weights = regionWeights(points, box, x, y, falloff * ctx.faceWidth);
+  const hit = weights.flatMap((w, k) => w > 0 ? [k] : []);
+  if (hit.length === 0) {
+    const fx = points.map(([px]) => (px - box.x0) / bw(box));
+    const fy = points.map(([, py]) => (box.y1 - py) / bh(box));
+    const range = (v) => `[${roundTo(Math.min(...v), 0.01)}, ${roundTo(Math.max(...v), 0.01)}]`;
+    throw new PatchError(
+      `${name}.region (falloff ${falloff}) catches none of ${target}'s ${points.length} points; at rest they span x ${range(fx)}, y ${range(fy)} of ${role}'s box`
+    );
+  }
+  let sum = sums.get(stop.offsets);
+  if (sum === void 0) {
+    sum = {
+      terms: stop.offsets.map(() => []),
+      scale: stop.scale,
+      step: stop.step
+    };
+    sums.set(stop.offsets, sum);
+  }
+  const ddx = dx * ctx.faceWidth;
+  const ddy = -dy * ctx.faceWidth;
+  for (const k of hit) {
+    sum.terms[2 * k].push(ddx * weights[k]);
+    sum.terms[2 * k + 1].push(ddy * weights[k]);
+  }
+  const maxW = Math.max(...hit.map((k) => weights[k]));
+  const report = {
+    index: i,
+    target,
+    at,
+    moved: hit.length,
+    of: points.length,
+    maxPx: roundTo(maxW * Math.hypot(dx, dy) * ctx.faceWidth, 0.1)
+  };
+  if (stop.stride !== void 0) {
+    const { stride } = stop;
+    const cols = hit.map((k) => k % stride);
+    const rows = hit.map((k) => Math.floor(k / stride));
+    report.cols = [Math.min(...cols), Math.max(...cols)];
+    report.rows = [Math.min(...rows), Math.max(...rows)];
+  }
+  return report;
+}
+function resolveStop(name, target, at, ctx) {
+  const grid = ctx.grids.get(target);
+  if (grid !== void 0) {
+    const l = grid.lattice.points;
+    const points = [];
+    for (let k = 0; k < l.length; k += 2) points.push([l[k], l[k + 1]]);
+    return {
+      offsets: gridStop(name, at, target, grid.keyforms),
+      points,
+      scale: [1, 1],
+      step: 0.1,
+      stride: grid.lattice.cols + 1
+    };
+  }
+  const part = ctx.parts.find((p) => p.id === target);
+  const b = ctx.boxOf(target);
+  if (part?.mesh === void 0 || part.warps === void 0 || b === void 0) {
+    const parts = ctx.parts.filter(
+      (p) => p.mesh !== void 0 && p.warps !== void 0 && ctx.boxOf(p.id) !== void 0
+    );
+    throw new PatchError(
+      `${name}.target "${target}" is neither a feature grid (${[...ctx.grids.keys()].join(", ")}) nor a mesh part with warps (${parts.map((p) => p.id).join(", ")}); bodyWarp and the matrix deformers are not patchable`
+    );
+  }
+  return {
+    offsets: partStop(name, at, part, part.warps, ctx),
+    points: meshPoints(part.mesh, b),
+    scale: [bw(b), bh(b)],
+    step: 1e-4
+  };
+}
+function gridStop(name, at, id, keyforms) {
+  const i = X_STOPS.indexOf(at[import_format11.StandardParameter.AngleX]);
+  const j = Y_STOPS.indexOf(at[import_format11.StandardParameter.AngleY]);
+  if (Object.keys(at).length !== 2 || i < 0 || j < 0) {
+    throw new PatchError(
+      `${name}.at must name ${import_format11.StandardParameter.AngleX} in [${X_STOPS.join(", ")}] and ${import_format11.StandardParameter.AngleY} in [${Y_STOPS.join(", ")}] for the grid ${id}, got ${JSON.stringify(at)}`
+    );
+  }
+  if (X_STOPS[i] === 0 && Y_STOPS[j] === 0) {
+    throw new PatchError(
+      `${name}.at ${import_format11.StandardParameter.AngleX}=0 ${import_format11.StandardParameter.AngleY}=0 is ${id}'s rest stop: ${REST_IS_ART}; patch a stop with ${import_format11.StandardParameter.AngleX} or ${import_format11.StandardParameter.AngleY} at \xB130 instead`
+    );
+  }
+  return keyforms[j * X_STOPS.length + i];
+}
+function partStop(name, at, part, warps, ctx) {
+  const keys = Object.keys(at);
+  const [param] = keys;
+  const value = at[param];
+  const keyform = keys.length === 1 ? warps.filter((w) => w.parameter === param).flatMap((w) => w.keyforms).find((k) => k.value === value) : void 0;
+  if (keyform === void 0) {
+    throw new PatchError(
+      `${name}.at must name one parameter at one of ${part.id}'s warp stops (${listStops(warps, () => true)}), got ${JSON.stringify(at)}`
+    );
+  }
+  if (ROLLS.has(param)) {
+    throw new PatchError(
+      `${name}.at ${param}: that parameter rolls ${part.id}'s deformer chain, so a displacement at its stop is not on screen axes; patch another of its stops (${listStops(warps, (p) => !ROLLS.has(p))}) or its feature grid instead`
+    );
+  }
+  const isRest = (p, v) => v === ctx.parameters.find((q) => q.id === p)?.default;
+  const isShut = (p, v) => SHUT_BY.get(part.id) === p && v === 0;
+  if (!isRest(param, value) && !isShut(param, value)) return keyform.offsets;
+  const open = listStops(warps, (p, v) => !isRest(p, v) && !isShut(p, v));
+  const grid = part.deformer !== void 0 && ctx.grids.has(part.deformer) ? `its feature grid ${part.deformer} at a ${import_format11.StandardParameter.AngleX} \xD7 ${import_format11.StandardParameter.AngleY} stop` : "";
+  const instead = [open && `another of its stops (${open})`, grid].filter((s) => s !== "").join(" or ");
+  const hint = instead === "" ? "" : `; patch ${instead} instead`;
+  throw new PatchError(
+    isRest(param, value) ? `${name}.at ${param}=${value} is that parameter's default, ${part.id}'s rest stop: ${REST_IS_ART}${hint}` : `${name}.at ${param}=0 is where the rig shuts ${part.id} on purpose, a closure the fold check exempts, so a fold a patch made there would never be reported${hint}`
+  );
+}
+function listStops(warps, keep) {
+  const stops = /* @__PURE__ */ new Map();
+  for (const w of warps) {
+    for (const k of w.keyforms) {
+      if (!keep(w.parameter, k.value)) continue;
+      const s = stops.get(w.parameter) ?? /* @__PURE__ */ new Set();
+      s.add(k.value);
+      stops.set(w.parameter, s);
+    }
+  }
+  return [...stops].map(([p, s]) => `${p}@${[...s].sort((a, b) => a - b).join(",")}`).join(" ");
+}
+function regionWeights(points, box, x, y, fall) {
+  const x0 = box.x0 + x[0] * bw(box);
+  const x1 = box.x0 + x[1] * bw(box);
+  const top = box.y1 - y[0] * bh(box);
+  const bottom = box.y1 - y[1] * bh(box);
+  return points.map(([px, py]) => {
+    const d = Math.hypot(
+      Math.max(x0 - px, 0, px - x1),
+      Math.max(bottom - py, 0, py - top)
+    );
+    return d === 0 ? 1 : d < fall ? smoothstep(fall, 0, d) : 0;
+  });
+}
+function asPatch(check) {
+  try {
+    return check();
+  } catch (e) {
+    throw e instanceof TurnTargetError ? new PatchError(e.message) : e;
+  }
+}
+function fields(name, v, known) {
+  if (v === void 0) throw new PatchError(`${name} is missing`);
+  asPatch(() => checkedKeys(name, v, known));
+  return v;
+}
+function numbers(name, v) {
+  const o = fields(name, v, Object.keys(v ?? {}));
+  return Object.fromEntries(
+    Object.entries(o).map(([k, n]) => [k, finite2(`${name}.${k}`, n)])
+  );
+}
+var finite2 = (name, v, lo = -Infinity) => asPatch(() => checkedNumber(name, v, lo, Infinity));
+function text(name, v) {
+  if (typeof v !== "string") {
+    throw new PatchError(`${name} must be a string, got ${String(v)}`);
+  }
+  return v;
+}
+function span(name, v) {
+  if (!Array.isArray(v) || v.length !== 2) {
+    throw new PatchError(
+      `${name} must be [from, to], got ${JSON.stringify(v)}`
+    );
+  }
+  const lo = finite2(`${name}[0]`, v[0]);
+  const hi = finite2(`${name}[1]`, v[1]);
+  if (lo > hi) {
+    throw new PatchError(
+      `${name} [${lo}, ${hi}] runs backwards: ${name}[0] must not exceed ${name}[1]`
+    );
+  }
+  return [lo, hi];
+}
+
 // src/auto-rig/generate.ts
 var MESH_CELLS = {
   face: { px: 28, min: 4, max: 24 },
@@ -6016,8 +6267,17 @@ function generateIkiFromLayerSet(layers, canvas, options = {}) {
     ];
   }
   const parameters = declareParameters(new Set(byRole.keys()));
+  const reports = options.patches === void 0 ? void 0 : applyPatches(options.patches, {
+    grids: new Map(
+      [...grids].map(([family, g]) => [WARP_ID[family], g])
+    ),
+    parts,
+    boxOf: (role) => has(role) ? box(role) : void 0,
+    faceWidth: byRole.get("face").cropW,
+    parameters
+  });
   const model = {
-    version: import_format10.IKI_FORMAT_VERSION,
+    version: import_format12.IKI_FORMAT_VERSION,
     name: "auto-rigged",
     canvas: { width: canvas.width, height: canvas.height },
     parameters,
@@ -6027,7 +6287,8 @@ function generateIkiFromLayerSet(layers, canvas, options = {}) {
     expressions: defaultExpressions(new Set(parameters.map((p) => p.id))),
     motions: defaultMotions(new Set(parameters.map((p) => p.id)))
   };
-  const valid = (0, import_format10.parseIkiModel)(model);
+  const valid = (0, import_format12.parseIkiModel)(model);
+  if (reports !== void 0) options.onPatchesApplied?.(reports);
   if (hasNose && options.onTurnSolved) {
     options.onTurnSolved(
       turnReport(
@@ -6042,14 +6303,14 @@ function generateIkiFromLayerSet(layers, canvas, options = {}) {
 function turnWarps(mesh, b, fieldOf) {
   return [
     localWarp(
-      import_format10.StandardParameter.AngleX,
+      import_format12.StandardParameter.AngleX,
       mesh,
       b,
       X_STOPS,
       ([x, y], v, i) => v === 0 ? [0, 0] : [fieldOf(i)(x, y, v, 0)[0], 0]
     ),
     localWarp(
-      import_format10.StandardParameter.AngleY,
+      import_format12.StandardParameter.AngleY,
       mesh,
       b,
       Y_STOPS,
@@ -6100,7 +6361,7 @@ function buildPart(spec, b, order, frame, byRole, style, frontGrid, lips) {
   }
   if (mesh !== void 0) part.mesh = mesh;
   const side = spec.role.endsWith("_L") ? "L" : "R";
-  const eyeOpen = side === "L" ? import_format10.StandardParameter.EyeOpenLeft : import_format10.StandardParameter.EyeOpenRight;
+  const eyeOpen = side === "L" ? import_format12.StandardParameter.EyeOpenLeft : import_format12.StandardParameter.EyeOpenRight;
   const hh = frame.hh;
   switch (spec.role) {
     case "face":
@@ -6115,7 +6376,7 @@ function buildPart(spec, b, order, frame, byRole, style, frontGrid, lips) {
             headOwnRoll(byRole.has("body"))
           ),
           localWarp(
-            import_format10.StandardParameter.Breath,
+            import_format12.StandardParameter.Breath,
             mesh,
             b,
             [0, 1],
@@ -6162,8 +6423,8 @@ function buildPart(spec, b, order, frame, byRole, style, frontGrid, lips) {
       if (byRole.has("mouth_open")) {
         warps.push(mouthWiden(mesh, b));
         bindings.push(
-          { parameter: import_format10.StandardParameter.MouthOpen, channel: "opacity", from: 1, to: 0 },
-          { parameter: import_format10.StandardParameter.MouthOpen, channel: "opacity", from: 1, to: 0 }
+          { parameter: import_format12.StandardParameter.MouthOpen, channel: "opacity", from: 1, to: 0 },
+          { parameter: import_format12.StandardParameter.MouthOpen, channel: "opacity", from: 1, to: 0 }
         );
         extra = [(AMPLITUDE.mouthOpenWidth - 1) * (bw(b) / 2), 0];
       } else {
@@ -6173,19 +6434,19 @@ function buildPart(spec, b, order, frame, byRole, style, frontGrid, lips) {
         );
         bindings.push(
           {
-            parameter: import_format10.StandardParameter.MouthOpen,
+            parameter: import_format12.StandardParameter.MouthOpen,
             channel: "scaleY",
             from: 0,
             to: roundTo(grow, 0.01)
           },
           {
-            parameter: import_format10.StandardParameter.MouthOpen,
+            parameter: import_format12.StandardParameter.MouthOpen,
             channel: "scaleX",
             from: 0,
             to: roundTo(AMPLITUDE.mouthOpenWidth - 1, 0.01)
           },
           {
-            parameter: import_format10.StandardParameter.MouthOpen,
+            parameter: import_format12.StandardParameter.MouthOpen,
             channel: "translateY",
             from: 0,
             to: -roundTo(grow * bh(b) / 2, 0.01)
@@ -6197,7 +6458,7 @@ function buildPart(spec, b, order, frame, byRole, style, frontGrid, lips) {
     case "mouth_open":
       warps.push(mouthForm(mesh, b), mouthOpenGrow(mesh, b));
       bindings.push({
-        parameter: import_format10.StandardParameter.MouthOpen,
+        parameter: import_format12.StandardParameter.MouthOpen,
         channel: "opacity",
         from: 0,
         to: 1
@@ -6219,7 +6480,7 @@ function buildPart(spec, b, order, frame, byRole, style, frontGrid, lips) {
     case "blush_L":
     case "blush_R":
       bindings.push({
-        parameter: import_format10.StandardParameter.Cheek,
+        parameter: import_format12.StandardParameter.Cheek,
         channel: "opacity",
         from: AMPLITUDE.blushRest,
         to: 1
@@ -6230,8 +6491,8 @@ function buildPart(spec, b, order, frame, byRole, style, frontGrid, lips) {
       if (byRole.has("hair_front")) {
         const amp = style.sway * AMPLITUDE.sway * hh;
         warps.push(
-          hairSway(import_format10.StandardParameter.HairSwayX, mesh, b, amp),
-          hairSway(import_format10.StandardParameter.HairSwayZ, mesh, b, amp)
+          hairSway(import_format12.StandardParameter.HairSwayX, mesh, b, amp),
+          hairSway(import_format12.StandardParameter.HairSwayZ, mesh, b, amp)
         );
       }
       warps.push(tiltHang(mesh, b, pivot, hairHangWeight(frame.chinY, b.y0)));
@@ -6297,9 +6558,9 @@ function deformers(frame, grids, bodyWarp, arms, byRole) {
     pivot: { x: roundTo(frame.axisX, 0.01), y: roundTo(frame.chinY, 0.01) },
     bindings: [
       // AngleZ is clockwise-positive (Live2D's); a rotation is CCW-positive.
-      { parameter: import_format10.StandardParameter.AngleZ, channel: "rotate", from: roll, to: -roll },
+      { parameter: import_format12.StandardParameter.AngleZ, channel: "rotate", from: roll, to: -roll },
       {
-        parameter: import_format10.StandardParameter.Breath,
+        parameter: import_format12.StandardParameter.Breath,
         channel: "translateY",
         from: 0,
         to: roundTo(headOwnBreath(hasBody) * frame.hh, 0.01)
@@ -6317,8 +6578,8 @@ function deformers(frame, grids, bodyWarp, arms, byRole) {
         points: g.lattice.points
       },
       warp2d: {
-        parameter: import_format10.StandardParameter.AngleX,
-        parameterY: import_format10.StandardParameter.AngleY,
+        parameter: import_format12.StandardParameter.AngleX,
+        parameterY: import_format12.StandardParameter.AngleY,
         valuesX: X_STOPS,
         valuesY: Y_STOPS,
         keyforms2d: g.keyforms.map((offsets) => ({ offsets }))
@@ -6331,16 +6592,16 @@ function hairPhysics() {
   return [
     {
       id: "hairSway",
-      input: { parameter: import_format10.StandardParameter.AngleX, weight: 1 },
-      output: { parameter: import_format10.StandardParameter.HairSwayX, scale: 5 },
+      input: { parameter: import_format12.StandardParameter.AngleX, weight: 1 },
+      output: { parameter: import_format12.StandardParameter.HairSwayX, scale: 5 },
       mass: 1,
       stiffness: 30,
       damping: 3
     },
     {
       id: "hairTilt",
-      input: { parameter: import_format10.StandardParameter.AngleZ, weight: 1 },
-      output: { parameter: import_format10.StandardParameter.HairSwayZ, scale: 8 },
+      input: { parameter: import_format12.StandardParameter.AngleZ, weight: 1 },
+      output: { parameter: import_format12.StandardParameter.HairSwayZ, scale: 8 },
       mass: 1,
       stiffness: 25,
       damping: 2.5
@@ -6350,13 +6611,13 @@ function hairPhysics() {
 function declareParameters(roles) {
   const out = [];
   const add = (id, name, min, max, def) => out.push({ id, name, min, max, default: def });
-  add(import_format10.StandardParameter.AngleX, "Head Angle", -30, 30, 0);
-  add(import_format10.StandardParameter.AngleY, "Head Angle Y", -30, 30, 0);
-  add(import_format10.StandardParameter.AngleZ, "Head Angle Z", -30, 30, 0);
+  add(import_format12.StandardParameter.AngleX, "Head Angle", -30, 30, 0);
+  add(import_format12.StandardParameter.AngleY, "Head Angle Y", -30, 30, 0);
+  add(import_format12.StandardParameter.AngleZ, "Head Angle Z", -30, 30, 0);
   if (roles.has("body")) {
-    add(import_format10.StandardParameter.BodyAngleX, "Body Angle X", -10, 10, 0);
-    add(import_format10.StandardParameter.BodyAngleY, "Body Angle Y", -10, 10, 0);
-    add(import_format10.StandardParameter.BodyAngleZ, "Body Angle Z", -10, 10, 0);
+    add(import_format12.StandardParameter.BodyAngleX, "Body Angle X", -10, 10, 0);
+    add(import_format12.StandardParameter.BodyAngleY, "Body Angle Y", -10, 10, 0);
+    add(import_format12.StandardParameter.BodyAngleZ, "Body Angle Z", -10, 10, 0);
   }
   const addPose = (side, pose, angle) => {
     add(pose, `Arm Pose ${side}`, 0, 1, 0);
@@ -6365,40 +6626,40 @@ function declareParameters(roles) {
   const [armMin, armMax] = ARM_RANGE;
   const [elbowMin, elbowMax] = ELBOW_RANGE;
   if (roles.has("arm_L")) {
-    add(import_format10.StandardParameter.ArmLeft, "Arm L", armMin, armMax, 0);
-    add(import_format10.StandardParameter.ElbowLeft, "Elbow L", elbowMin, elbowMax, 0);
+    add(import_format12.StandardParameter.ArmLeft, "Arm L", armMin, armMax, 0);
+    add(import_format12.StandardParameter.ElbowLeft, "Elbow L", elbowMin, elbowMax, 0);
     if (roles.has("forearm_pose_L"))
-      addPose("L", import_format10.StandardParameter.ArmPoseLeft, import_format10.StandardParameter.ArmPoseAngleLeft);
+      addPose("L", import_format12.StandardParameter.ArmPoseLeft, import_format12.StandardParameter.ArmPoseAngleLeft);
   }
   if (roles.has("arm_R")) {
-    add(import_format10.StandardParameter.ArmRight, "Arm R", armMin, armMax, 0);
-    add(import_format10.StandardParameter.ElbowRight, "Elbow R", elbowMin, elbowMax, 0);
+    add(import_format12.StandardParameter.ArmRight, "Arm R", armMin, armMax, 0);
+    add(import_format12.StandardParameter.ElbowRight, "Elbow R", elbowMin, elbowMax, 0);
     if (roles.has("forearm_pose_R"))
-      addPose("R", import_format10.StandardParameter.ArmPoseRight, import_format10.StandardParameter.ArmPoseAngleRight);
+      addPose("R", import_format12.StandardParameter.ArmPoseRight, import_format12.StandardParameter.ArmPoseAngleRight);
   }
-  add(import_format10.StandardParameter.EyeOpenLeft, "Eye L", 0, 1, 1);
-  add(import_format10.StandardParameter.EyeOpenRight, "Eye R", 0, 1, 1);
+  add(import_format12.StandardParameter.EyeOpenLeft, "Eye L", 0, 1, 1);
+  add(import_format12.StandardParameter.EyeOpenRight, "Eye R", 0, 1, 1);
   if ([...roles].some((r) => /^(iris|pupil|highlight)_/.test(r))) {
-    add(import_format10.StandardParameter.EyeballX, "Gaze X", -1, 1, 0);
-    add(import_format10.StandardParameter.EyeballY, "Gaze Y", -1, 1, 0);
+    add(import_format12.StandardParameter.EyeballX, "Gaze X", -1, 1, 0);
+    add(import_format12.StandardParameter.EyeballY, "Gaze Y", -1, 1, 0);
   }
-  add(import_format10.StandardParameter.MouthOpen, "Mouth Open", 0, 1, 0);
-  add(import_format10.StandardParameter.MouthForm, "Mouth Form", -1, 1, 0);
+  add(import_format12.StandardParameter.MouthOpen, "Mouth Open", 0, 1, 0);
+  add(import_format12.StandardParameter.MouthForm, "Mouth Form", -1, 1, 0);
   if (roles.has("brow_L")) {
-    add(import_format10.StandardParameter.BrowLeftY, "Brow L Y", -1, 1, 0);
-    add(import_format10.StandardParameter.BrowLeftAngle, "Brow L Angle", -1, 1, 0);
+    add(import_format12.StandardParameter.BrowLeftY, "Brow L Y", -1, 1, 0);
+    add(import_format12.StandardParameter.BrowLeftAngle, "Brow L Angle", -1, 1, 0);
   }
   if (roles.has("brow_R")) {
-    add(import_format10.StandardParameter.BrowRightY, "Brow R Y", -1, 1, 0);
-    add(import_format10.StandardParameter.BrowRightAngle, "Brow R Angle", -1, 1, 0);
+    add(import_format12.StandardParameter.BrowRightY, "Brow R Y", -1, 1, 0);
+    add(import_format12.StandardParameter.BrowRightAngle, "Brow R Angle", -1, 1, 0);
   }
   if (roles.has("blush_L") || roles.has("blush_R")) {
-    add(import_format10.StandardParameter.Cheek, "Cheek", 0, 1, 0);
+    add(import_format12.StandardParameter.Cheek, "Cheek", 0, 1, 0);
   }
-  add(import_format10.StandardParameter.Breath, "Breath", 0, 1, 0);
+  add(import_format12.StandardParameter.Breath, "Breath", 0, 1, 0);
   if (roles.has("hair_front")) {
-    add(import_format10.StandardParameter.HairSwayX, "Hair Sway X", -SWAY_RANGE, SWAY_RANGE, 0);
-    add(import_format10.StandardParameter.HairSwayZ, "Hair Sway Z", -SWAY_RANGE, SWAY_RANGE, 0);
+    add(import_format12.StandardParameter.HairSwayX, "Hair Sway X", -SWAY_RANGE, SWAY_RANGE, 0);
+    add(import_format12.StandardParameter.HairSwayZ, "Hair Sway Z", -SWAY_RANGE, SWAY_RANGE, 0);
   }
   return out;
 }
@@ -6420,6 +6681,8 @@ function declareParameters(roles) {
   LIP_INSIDE_ROLES,
   LIP_ROLES,
   LayerGeometryError,
+  PatchError,
+  SHUT_BY,
   SPECK_CORE_FRACTION,
   SetDeformerBindings,
   SetDeformerParent,