spine-rigc 2.18.0 → 2.19.0

package/src/meshreduce.ts

@@ -0,0 +1,1294 @@
+/**
+ * Mesh reduction and local refinement — stage B2 of the contract in
+ * docs/MESH_REDUCTION.md (issue #1221, stage B: issue #1224).
+ *
+ * One operation is exported, `reduceMesh`, and it is two operations composed:
+ *
+ * 1. **Refinement** (`refineRegions`) inserts vertices inside the union of the
+ *    declared regions and their bands until §5's `L(R)` holds on every edge
+ *    that meets each region — a coarse source is refined, never refused
+ *    (correction 3).
+ * 2. **Reduction** (`removeVertices`) then removes source vertices one at a
+ *    time, retriangulating the hole each leaves, and takes a step only when
+ *    every bound the caller declared still holds after it — the region bounds
+ *    included, so the reduction cannot undo the refinement.
+ *
+ * Each is its own function with its own entry and exit, so a control can run
+ * one with the other idle — regions empty, or every source vertex protected —
+ * which is the shape the consumer asked for (spine-parts#126, comment
+ * 6042150608: "separate composed operations … with independently passing
+ * controls for each").
+ *
+ * ## What every step is held to
+ *
+ * Each candidate step is measured by `measureMeshQuality` (`src/meshquality.ts`)
+ * — no row is re-implemented here — and taken only when every row the caller's
+ * contract requires is `pass`: the art fit at `targets.artFit`, the boundary
+ * deviation from the source hull at `targets.maxBoundaryDeviation`, the minimum
+ * angle when declared, orientation and degeneracy at 0, and every region's
+ * `MQ_MAX_EDGE` and `MQ_TRANSITION`. Before the measurement, the structural
+ * conditions a row cannot see: the hole's link polygon is strictly simple and
+ * ear-clips, the outline is still one loop, every protected source edge is
+ * still an edge, and no new edge joins two vertices whose weight vectors differ
+ * by more than `weightJump` (§6, conditions (a) and (b)).
+ *
+ * ## The order, which is the determinism (A18)
+ *
+ * The reduction sweeps the surviving SOURCE vertices in ascending source index,
+ * one removal attempted per vertex per pass; a step taken stays taken and the
+ * sweep continues with the next index. A pass in which no step is taken ends
+ * the reduction (`no-further-valid-reduction`, naming the constraint that
+ * blocked the last attempt). Inserted vertices are never candidates: they exist
+ * to meet `L(R)`, and removing one is undoing the refinement.
+ *
+ * The refinement measures, takes the first failing region row in report order
+ * (code, then region name) and splits that row's worst edge: at its midpoint
+ * when the midpoint lies in the region or its band, otherwise at the point of
+ * the edge inside them nearest the midpoint. A region no edge meets — one
+ * inside a single triangle — gets the first vertex of its polygon inserted into
+ * the triangle that holds it. Every inserted position is on the `r6` grid.
+ *
+ * ## What it never does
+ *
+ * - **Invent a value.** Every bound, floor, limit and the budget are inputs; a
+ *   missing one is `REDUCE_INPUT_MISSING`, thrown.
+ * - **Resample a survivor.** A surviving vertex keeps its position, UV and
+ *   bindings bit for bit (P19); only the order of its bindings is the canonical
+ *   one (strongest first, `boneOrder` on a tie).
+ * - **Bind.** A `SourceMesh` names bones and carries no bind coordinates, and
+ *   the input carries no bone transforms, so an inserted vertex's weights are
+ *   by bone name exactly as a source vertex's are; the compiler binds them, as
+ *   `bindWeightedVertices` binds every generated mesh.
+ * - **Claim a minimum.** A local stop is reported as one.
+ * - Pose, or link the runtime. Pure: no clock, no randomness, nothing from the
+ *   compiler.
+ */
+import {
+  distanceToSegment,
+  earClip,
+  findSelfIntersection,
+  labelIslands,
+  artOf,
+  MeshError,
+  MeshReductionError,
+  meshEdges,
+  r6,
+  rasteriseTriangles,
+  signedArea,
+  traceOutline,
+  checkHullOrder,
+} from './mesh.ts';
+import {
+  measureMeshQuality,
+  type AttachmentRef,
+  type ArtFitBounds,
+  type CandidateReport,
+  type DeformKeyInput,
+  type EffectiveSettings,
+  type MeasureRow,
+  type MeshCounts,
+  type MeshMeasureInput,
+  type MeshQualityReport,
+  type MeshReductionInput,
+  type RefinementRegion,
+  type ReductionChanges,
+  type SourceMesh,
+  type Termination,
+} from './meshquality.ts';
+
+// ---------------------------------------------------------------------------
+// the result
+// ---------------------------------------------------------------------------
+
+/** A `vertices` key after the remap: the run rewritten over the result's vertex order. */
+export interface RemappedDeformKey {
+  animation: string;
+  attachment: AttachmentRef;
+  /** The key's position in its timeline's `keys`. */
+  key: number;
+  time: number;
+  /** Into the RESULT's deform array, as the compiler emits it. */
+  offset: number;
+  vertices: number[];
+  /** Source vertices whose offsets the run carried and whose vertex the reduction removed — dropped, never moved onto another vertex. */
+  droppedVertices: number[];
+}
+
+/** A `transform` key: re-evaluated over the new geometry at compile, so it has no run to rewrite. */
+export interface DeformKeyRef {
+  animation: string;
+  attachment: AttachmentRef;
+  key: number;
+  time: number;
+}
+
+/**
+ * The reduced mesh: §1's `SourceMesh` in the canonical output order, plus what a
+ * consumer needs to carry anything indexed by the old vertices across.
+ */
+export interface ReducedMesh extends SourceMesh {
+  /** `meshEdges`' list, in the export encoding (index × 2), outline loop first. */
+  edges: number[];
+  /** Source index → result index; null where the reduction removed the vertex. */
+  indexMap: Array<number | null>;
+  /** Result indices of the vertices the refinement inserted, ascending. */
+  inserted: number[];
+  /** Every linked mesh of the source, echoed: each inherits this topology. */
+  linkedMeshes: AttachmentRef[];
+  /** P18: what happened to every deform key the input listed. */
+  deform: { remapped: RemappedDeformKey[]; reevaluated: DeformKeyRef[] };
+  counts: MeshCounts;
+}
+
+export interface MeshReductionResult {
+  /** Null when no mesh is returned: a refusal, or a budget that ran out before any candidate met the targets. */
+  mesh: ReducedMesh | null;
+  report: MeshQualityReport;
+}
+
+// ---------------------------------------------------------------------------
+// refusals and small helpers
+// ---------------------------------------------------------------------------
+
+type Pt = readonly [number, number];
+type Binding = { bone: string; weight: number };
+
+/** The predicate epsilon `segmentsMeet` and `prunePolygon` use (`src/mesh.ts`), for "on the boundary". */
+const ON_BOUNDARY = 1e-9;
+
+/** How many halvings toward a point known to lie in a region's band the split search tries before it says none was found. */
+const SPLIT_SEARCH_STEPS = 40;
+
+function nameOf(ref: AttachmentRef): string {
+  return `${ref.skin ?? '(no skin)'}/${ref.slot}/${ref.attachment}`;
+}
+
+function sameRef(a: AttachmentRef, b: AttachmentRef): boolean {
+  return a.skin === b.skin && a.slot === b.slot && a.attachment === b.attachment;
+}
+
+function refuse(code: string, message: string): never {
+  throw new MeshReductionError(code, message);
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function isRef(value: unknown): value is AttachmentRef {
+  return isObject(value) && typeof value.slot === 'string' && value.slot !== '' && typeof value.attachment === 'string' && value.attachment !== '' && (value.skin === null || typeof value.skin === 'string');
+}
+
+/** A refusal the operation reports rather than throws: the input is well formed and the request cannot be met. */
+class Stop extends Error {
+  constructor(
+    readonly reason: 'invalid-input' | 'unsupported-topology',
+    readonly code: string,
+    readonly detail: string,
+  ) {
+    super(`${code}: ${detail}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// validation — what is refused by a throw, before anything is measured
+// ---------------------------------------------------------------------------
+
+function checkFit(who: string, field: string, fit: unknown): void {
+  if (fit === undefined || fit === null || !isObject(fit)) refuse('REDUCE_INPUT_MISSING', `${who}: ${field} is ${JSON.stringify(fit)}; required { minCoverage, maxOvershoot, maxUndercut } — no field has a default`);
+  if (!isFiniteNumber(fit.minCoverage) || fit.minCoverage < 0 || fit.minCoverage > 1) refuse('REDUCE_INPUT_MISSING', `${who}: ${field}.minCoverage is ${JSON.stringify(fit.minCoverage)}; required a fraction in 0..1`);
+  for (const k of ['maxOvershoot', 'maxUndercut'] as const) {
+    if (!isFiniteNumber(fit[k]) || (fit[k] as number) < 0) refuse('REDUCE_INPUT_MISSING', `${who}: ${field}.${k} is ${JSON.stringify(fit[k])}; required a finite number of px, 0 or more`);
+  }
+}
+
+/**
+ * The fields a reduction reads and a measurement does not, refused by name. The
+ * art, the mesh's arrays, the regions' shapes and the sample floors are refused
+ * by `measureMeshQuality`'s own validation when the source is first measured,
+ * with the same codes.
+ */
+function validateReduction(input: MeshReductionInput): void {
+  if (!isObject(input)) refuse('REDUCE_INPUT_MISSING', `the input is ${JSON.stringify(input)}; required a MeshReductionInput object`);
+  if (!isRef(input.attachment)) refuse('REDUCE_INPUT_MISSING', `attachment is ${JSON.stringify(input.attachment)}; required { skin: string | null, slot: string, attachment: string }`);
+  const who = `attachment ${nameOf(input.attachment)}`;
+  checkFit(who, 'sourceBounds', input.sourceBounds);
+  const t = input.targets;
+  if (!isObject(t)) refuse('REDUCE_INPUT_MISSING', `${who}: targets is ${JSON.stringify(t)}; required { artFit, maxBoundaryDeviation, regions }`);
+  checkFit(who, 'targets.artFit', t.artFit);
+  if (!isFiniteNumber(t.maxBoundaryDeviation) || t.maxBoundaryDeviation < 0) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: targets.maxBoundaryDeviation is ${JSON.stringify(t.maxBoundaryDeviation)}; required a finite number of px, 0 or more (P13: the required preservation bound)`);
+  }
+  if (!Array.isArray(t.regions)) refuse('REDUCE_INPUT_MISSING', `${who}: targets.regions is ${JSON.stringify(t.regions)}; required a list (empty when none)`);
+  const b = input.budget;
+  if (!isObject(b) || !Number.isInteger(b.maxCandidates) || (b.maxCandidates as number) < 0) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: budget is ${JSON.stringify(b)}; required { maxCandidates: a whole number, 0 or more } — the work bound has no default`);
+  }
+  const src = input.source;
+  if (!isObject(src) || !Array.isArray(src.points)) refuse('REDUCE_INPUT_MISSING', `${who}: source is not { points, uvs, triangles, hull, weights }`);
+  const n = src.points.length;
+
+  const p = input.protect;
+  if (p === undefined || p === null || !isObject(p)) refuse('REDUCE_INPUT_MISSING', `${who}: protect is ${JSON.stringify(p)}; required a ProtectedFeatures — a reduction has no default protection (P20)`);
+  if (typeof p.hull !== 'boolean') refuse('REDUCE_INPUT_MISSING', `${who}: protect.hull is ${JSON.stringify(p.hull)}; required true or false (P20: no default inside the operation)`);
+  if (!Array.isArray(p.vertices) || !Array.isArray(p.edges) || !Array.isArray(p.regionBoundaries) || !Array.isArray(p.influences) || !(p.weightJump === null || (isFiniteNumber(p.weightJump) && p.weightJump >= 0))) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: protect is not { hull, vertices, edges, regionBoundaries, weightJump, influences } with lists and a weightJump that is null or 0 or more`);
+  }
+  p.vertices.forEach((v, i) => {
+    if (!Number.isInteger(v) || v < 0 || v >= n) refuse('REDUCE_INPUT_MISSING', `${who}: protect.vertices[${i}] is ${JSON.stringify(v)}; required a source vertex index in 0..${n - 1}`);
+  });
+  const sourceEdges = new Set<string>();
+  if (Array.isArray(src.triangles)) {
+    for (let i = 0; i + 2 < src.triangles.length; i += 3) {
+      const tri = [src.triangles[i], src.triangles[i + 1], src.triangles[i + 2]];
+      for (let k = 0; k < 3; k++) sourceEdges.add(edgeKey(tri[k], tri[(k + 1) % 3]));
+    }
+  }
+  p.edges.forEach((e, i) => {
+    if (!Array.isArray(e) || e.length !== 2 || !sourceEdges.has(edgeKey(e[0], e[1]))) {
+      refuse('REDUCE_INPUT_MISSING', `${who}: protect.edges[${i}] is ${JSON.stringify(e)}; required a pair of source indices that is an edge of a source triangle`);
+    }
+  });
+  const regionNames = new Set(t.regions.map((r) => (isObject(r) ? r.name : undefined)));
+  p.regionBoundaries.forEach((name, i) => {
+    if (!regionNames.has(name)) refuse('REDUCE_INPUT_MISSING', `${who}: protect.regionBoundaries[${i}] is ${JSON.stringify(name)}, which no region in targets.regions is; required a declared region's name`);
+  });
+
+  const weighted = src.weights !== null && src.weights !== undefined;
+  if (weighted) {
+    const lim = input.influences;
+    if (lim === undefined || lim === null || !isObject(lim)) refuse('REDUCE_INPUT_MISSING', `${who}: influences is ${JSON.stringify(lim)} on a weighted source; required { maxInfluences, minWeight } — stated on every weighted call, never inherited (P19)`);
+    if (!Number.isInteger(lim.maxInfluences) || lim.maxInfluences < 1) refuse('REDUCE_INPUT_MISSING', `${who}: influences.maxInfluences is ${JSON.stringify(lim.maxInfluences)}; required a whole number >= 1`);
+    if (!isFiniteNumber(lim.minWeight) || lim.minWeight < 0 || lim.minWeight >= 1) refuse('REDUCE_INPUT_MISSING', `${who}: influences.minWeight is ${JSON.stringify(lim.minWeight)}; required a share in 0..1 (0 drops only shares that are zero on the weight grid)`);
+    const order = input.boneOrder;
+    if (!Array.isArray(order) || order.some((x) => typeof x !== 'string')) refuse('REDUCE_INPUT_MISSING', `${who}: boneOrder is ${JSON.stringify(order)} on a weighted source; required the skeleton's bone names in order (correction 1: the weight tie-break)`);
+    if (new Set(order).size !== order.length) refuse('REDUCE_INPUT_MISSING', `${who}: boneOrder names a bone twice; required each bone once`);
+    const known = new Set(order);
+    if (Array.isArray(src.weights)) {
+      src.weights.forEach((vertex, i) => {
+        if (!Array.isArray(vertex)) return;
+        for (const bnd of vertex) {
+          if (isObject(bnd) && typeof bnd.bone === 'string' && !known.has(bnd.bone)) refuse('REDUCE_INPUT_MISSING', `${who}: source.weights[${i}] binds "${bnd.bone}", which boneOrder does not name; required every bound bone in boneOrder`);
+          if (isObject(bnd) && isFiniteNumber(bnd.weight) && bnd.weight < 0) refuse('REDUCE_INPUT_MISSING', `${who}: source.weights[${i}] gives "${String(bnd.bone)}" the weight ${bnd.weight}; required 0 or more`);
+        }
+      });
+    }
+    p.influences.forEach((bone, i) => {
+      if (!known.has(bone)) refuse('REDUCE_INPUT_MISSING', `${who}: protect.influences[${i}] is ${JSON.stringify(bone)}, which boneOrder does not name; required a bone of the skeleton`);
+    });
+  }
+
+  for (const field of ['minArtSamples', 'regionArtSamples', 'preset'] as const) {
+    if (input[field] === undefined) refuse('REDUCE_INPUT_MISSING', `${who}: ${field} is missing; required a value — no field has a default`);
+  }
+  if (!Array.isArray(input.linkedMeshes)) refuse('REDUCE_INPUT_MISSING', `${who}: linkedMeshes is ${JSON.stringify(input.linkedMeshes)}; required a list of the source's linked meshes (empty when none)`);
+  input.linkedMeshes.forEach((ref, i) => {
+    if (!isRef(ref)) refuse('REDUCE_INPUT_MISSING', `${who}: linkedMeshes[${i}] is ${JSON.stringify(ref)}; required an AttachmentRef`);
+  });
+  if (!Array.isArray(input.deform)) refuse('REDUCE_INPUT_MISSING', `${who}: deform is ${JSON.stringify(input.deform)}; required a list of the deform timelines keyed on the attachment and its linked meshes (empty when none)`);
+  input.deform.forEach((tl, i) => {
+    if (!isObject(tl) || typeof tl.animation !== 'string' || tl.animation === '' || !isRef(tl.attachment) || !Array.isArray(tl.keys)) {
+      refuse('REDUCE_INPUT_MISSING', `${who}: deform[${i}] is not { animation, attachment, keys }; required that`);
+    }
+    if (!sameRef(tl.attachment, input.attachment) && !input.linkedMeshes.some((l) => sameRef(l, tl.attachment))) {
+      refuse('REDUCE_INPUT_MISSING', `${who}: deform[${i}] (animation "${tl.animation}") is keyed on ${nameOf(tl.attachment)}, which is neither the attachment nor a listed linked mesh; required one of those`);
+    }
+    tl.keys.forEach((key, k) => {
+      const at = `${who}: deform[${i}] (animation "${tl.animation}") key ${k}`;
+      if (!isObject(key) || !isFiniteNumber(key.time)) refuse('REDUCE_INPUT_MISSING', `${at} has no finite time; required one`);
+      if (key.kind === 'vertices') {
+        if (!Number.isInteger(key.offset) || key.offset < 0) refuse('REDUCE_INPUT_MISSING', `${at}: offset is ${JSON.stringify(key.offset)}; required a whole index into the deform array, 0 or more`);
+        if (!Array.isArray(key.vertices) || key.vertices.some((v) => !isFiniteNumber(v))) refuse('REDUCE_INPUT_MISSING', `${at}: vertices is not a list of finite numbers; required the run as the compiler emits it`);
+      } else if (key.kind !== 'setup' && key.kind !== 'transform') {
+        refuse('REDUCE_INPUT_MISSING', `${at}: kind is ${JSON.stringify((key as { kind: unknown }).kind)}; required "setup", "vertices" or "transform"`);
+      }
+    });
+  });
+}
+
+function edgeKey(a: number, b: number): string {
+  return a < b ? `${a},${b}` : `${b},${a}`;
+}
+
+// ---------------------------------------------------------------------------
+// the working mesh — vertices by stable id: source index, then insertion order
+// ---------------------------------------------------------------------------
+
+interface Work {
+  /** Number of source vertices: ids below it are source indices, ids from it are insertions in order. */
+  nSource: number;
+  pos: Pt[];
+  uv: Array<[number, number]>;
+  weights: Binding[][] | null;
+  alive: boolean[];
+  triangles: Array<[number, number, number]>;
+  /** For an inserted id, the source triangle its UV and weights were interpolated in. */
+  sourceTriangle: Map<number, number>;
+}
+
+interface Canonical {
+  mesh: SourceMesh;
+  /** Result index → working id. */
+  order: number[];
+  /** Working id → result index. */
+  indexOf: Map<number, number>;
+}
+
+/**
+ * §1's canonical order, read off a working mesh — or a `MeshError` naming why
+ * its triangles are not one closed outline.
+ *
+ * 1. hull vertices in walk order, from the surviving hull vertex with the
+ *    smallest source index (an inserted one only when no source vertex is on
+ *    the hull), turning the way the source's own hull listing turns;
+ * 2. surviving interior source vertices, ascending source index;
+ * 3. inserted interior vertices, ascending by (y, x) on the `r6` grid;
+ * 4. triangles rotated to start at their smallest index, winding kept, sorted;
+ * 5. bindings strongest first, ties by the bone's position in `boneOrder`.
+ */
+function canonicalise(work: Work, sourceTurn: number, boneRank: Map<string, number>): Canonical {
+  const ids: number[] = [];
+  for (let id = 0; id < work.alive.length; id++) if (work.alive[id]) ids.push(id);
+  const compact = new Map<number, number>();
+  ids.forEach((id, i) => compact.set(id, i));
+  const flat: number[] = [];
+  for (const tri of work.triangles) for (const id of tri) flat.push(compact.get(id)!);
+  const outline = traceOutline(ids.length, flat);
+  let walk = outline.walk.map((i) => ids[i]);
+  const start = walk.indexOf(Math.min(...walk));
+  walk = [...walk.slice(start), ...walk.slice(0, start)];
+  const turn = Math.sign(signedArea(walk.map((id) => [work.pos[id][0], work.pos[id][1]])));
+  if (turn !== sourceTurn) walk = [walk[0], ...walk.slice(1).reverse()];
+  const onHull = new Set(walk);
+  const interiorSource = ids.filter((id) => !onHull.has(id) && id < work.nSource);
+  const interiorInserted = ids
+    .filter((id) => !onHull.has(id) && id >= work.nSource)
+    .sort((a, b) => work.pos[a][1] - work.pos[b][1] || work.pos[a][0] - work.pos[b][0] || a - b);
+  const order = [...walk, ...interiorSource, ...interiorInserted];
+  const indexOf = new Map<number, number>();
+  order.forEach((id, i) => indexOf.set(id, i));
+  const tris = work.triangles.map(([a, b, c]): [number, number, number] => {
+    const t: [number, number, number] = [indexOf.get(a)!, indexOf.get(b)!, indexOf.get(c)!];
+    const k = t.indexOf(Math.min(...t));
+    return [t[k], t[(k + 1) % 3], t[(k + 2) % 3]];
+  });
+  tris.sort((p, q) => p[0] - q[0] || p[1] - q[1] || p[2] - q[2]);
+  const mesh: SourceMesh = {
+    points: order.map((id): [number, number] => [work.pos[id][0], work.pos[id][1]]),
+    uvs: order.flatMap((id) => work.uv[id]),
+    triangles: tris.flat(),
+    hull: walk.length,
+    weights: work.weights === null ? null : order.map((id) => sortBindings(work.weights![id], boneRank)),
+  };
+  checkHullOrder({ hull: mesh.hull, walk: [...Array(mesh.hull).keys()] }, order.length);
+  return { mesh, order, indexOf };
+}
+
+/** Strongest first, ties by the bone's place in `boneOrder` — the values themselves untouched. */
+function sortBindings(list: readonly Binding[], boneRank: Map<string, number>): Binding[] {
+  return list.map((b) => ({ bone: b.bone, weight: b.weight })).sort((p, q) => q.weight - p.weight || (boneRank.get(p.bone) ?? 0) - (boneRank.get(q.bone) ?? 0));
+}
+
+// ---------------------------------------------------------------------------
+// plane geometry the steps need (the rows' own geometry stays in meshquality.ts)
+// ---------------------------------------------------------------------------
+
+function inClosedPolygon(p: Pt, poly: readonly Pt[]): boolean {
+  const n = poly.length;
+  for (let i = 0; i < n; i++) if (distanceToSegment(p, poly[i], poly[(i + 1) % n]) <= ON_BOUNDARY) return true;
+  let inside = false;
+  for (let i = 0, j = n - 1; i < n; j = i++) {
+    const [xi, yi] = poly[i];
+    const [xj, yj] = poly[j];
+    if (yi > p[1] !== yj > p[1] && p[0] < ((xj - xi) * (p[1] - yi)) / (yj - yi) + xi) inside = !inside;
+  }
+  return inside;
+}
+
+function distanceToBoundary(p: Pt, poly: readonly Pt[]): number {
+  let d = Infinity;
+  for (let i = 0; i < poly.length; i++) d = Math.min(d, distanceToSegment(p, poly[i], poly[(i + 1) % poly.length]));
+  return d;
+}
+
+/** Is `p` in the closed region or within its band — the set P16's checkable form confines an insertion to? */
+function inRegionOrBand(p: Pt, region: RefinementRegion): boolean {
+  return inClosedPolygon(p, region.polygon) || (region.transition > 0 && distanceToBoundary(p, region.polygon) <= region.transition);
+}
+
+/** Barycentric coordinates of `p` in the triangle a, b, c, or null for a triangle with no area. */
+function barycentric(p: Pt, a: Pt, b: Pt, c: Pt): [number, number, number] | null {
+  const det = (b[1] - c[1]) * (a[0] - c[0]) + (c[0] - b[0]) * (a[1] - c[1]);
+  if (Math.abs(det) < 1e-12) return null;
+  const l0 = ((b[1] - c[1]) * (p[0] - c[0]) + (c[0] - b[0]) * (p[1] - c[1])) / det;
+  const l1 = ((c[1] - a[1]) * (p[0] - c[0]) + (a[0] - c[0]) * (p[1] - c[1])) / det;
+  return [l0, l1, 1 - l0 - l1];
+}
+
+// ---------------------------------------------------------------------------
+// what an inserted vertex carries — §6: interpolate, then prune
+// ---------------------------------------------------------------------------
+
+interface Tally {
+  sharesDroppedOnGrid: number;
+  sharesPruned: number;
+}
+
+interface Interpolated {
+  uv: [number, number];
+  weights: Binding[] | null;
+  sourceTriangle: number;
+}
+
+/**
+ * UV and weights of a point by barycentric interpolation in the source triangle
+ * containing it — the first by triangle index whose smallest coordinate is the
+ * largest, so a point on a shared edge takes the lower-numbered triangle (the
+ * two agree there) and a point rounded a hair outside onto the grid still finds
+ * the triangle it belongs to.
+ */
+function interpolate(p: Pt, input: MeshReductionInput, boneRank: Map<string, number>, tally: Tally, who: string): Interpolated {
+  const src = input.source;
+  let best = -1;
+  let bestMin = -Infinity;
+  let bestL: [number, number, number] = [0, 0, 0];
+  for (let t = 0; t * 3 + 2 < src.triangles.length; t++) {
+    const [a, b, c] = [src.triangles[t * 3], src.triangles[t * 3 + 1], src.triangles[t * 3 + 2]];
+    const l = barycentric(p, src.points[a], src.points[b], src.points[c]);
+    if (l === null) continue;
+    const m = Math.min(...l);
+    if (m > bestMin + 1e-12) {
+      best = t;
+      bestMin = m;
+      bestL = l;
+    }
+  }
+  const clamped = bestL.map((v) => Math.max(0, v));
+  const sum = clamped[0] + clamped[1] + clamped[2];
+  const lam = clamped.map((v) => v / sum);
+  const corners = [src.triangles[best * 3], src.triangles[best * 3 + 1], src.triangles[best * 3 + 2]];
+  const uv: [number, number] = [0, 1].map((k) => r6(corners.reduce((s, v, i) => s + lam[i] * src.uvs[v * 2 + k], 0))) as [number, number];
+  if (src.weights === null) return { uv, weights: null, sourceTriangle: best };
+  const shares = new Map<string, number>();
+  corners.forEach((v, i) => {
+    for (const bnd of src.weights![v]) shares.set(bnd.bone, (shares.get(bnd.bone) ?? 0) + lam[i] * bnd.weight);
+  });
+  const where = `${who}: the vertex inserted at (${p[0]}, ${p[1]}) in source triangle ${best} (vertices ${corners.join(', ')})`;
+  return { uv, weights: prune(shares, input, boneRank, tally, where), sourceTriangle: best };
+}
+
+/**
+ * `InfluenceLimits` applied to one interpolated weight vector (§6, P19): the
+ * protected influences kept first, then the strongest others up to
+ * `maxInfluences`; shares under `minWeight` dropped; a positive share that is 0
+ * on the 6-decimal weight grid dropped and counted rather than written as a 0
+ * binding (`minWeight: 0` drops only those); the rest closed at `1 − others`,
+ * the `segmentShares` rule. Every bone it returns is one the source triangle
+ * carried — interpolation cannot name another.
+ */
+function prune(shares: Map<string, number>, input: MeshReductionInput, boneRank: Map<string, number>, tally: Tally, where: string): Binding[] {
+  const limits = input.influences!;
+  const guarded = new Set(input.protect.influences);
+  const rank = (bone: string): number => boneRank.get(bone) ?? 0;
+  let entries = [...shares.entries()].filter(([, s]) => s > 0).map(([bone, share]) => ({ bone, share }));
+  entries.sort((p, q) => q.share - p.share || rank(p.bone) - rank(q.bone));
+  const kept = entries.filter((e) => guarded.has(e.bone));
+  if (kept.length > limits.maxInfluences) {
+    throw new Stop(
+      'invalid-input',
+      'REDUCE_PROTECTED_INFLUENCES_OVER_CAP',
+      `${where} carries ${kept.length} protected influence(s) (${kept.map((e) => e.bone).join(', ')}); required at most influences.maxInfluences = ${limits.maxInfluences} — a protected influence is never pruned silently`,
+    );
+  }
+  for (const e of entries) {
+    if (guarded.has(e.bone)) continue;
+    if (kept.length < limits.maxInfluences) kept.push(e);
+    else tally.sharesPruned++;
+  }
+  entries = kept.sort((p, q) => q.share - p.share || rank(p.bone) - rank(q.bone));
+  const normalise = (): void => {
+    const total = entries.reduce((s, e) => s + e.share, 0);
+    for (const e of entries) e.share /= total;
+  };
+  normalise();
+  if (limits.minWeight > 0) {
+    const before = entries.length;
+    entries = entries.filter((e) => guarded.has(e.bone) || e.share >= limits.minWeight);
+    tally.sharesPruned += before - entries.length;
+    normalise();
+  }
+  for (;;) {
+    const zero = entries.find((e) => r6(e.share) === 0);
+    if (zero === undefined) break;
+    if (guarded.has(zero.bone)) {
+      throw new Stop(
+        'invalid-input',
+        'REDUCE_PROTECTED_INFLUENCE_BELOW_GRID',
+        `${where} gives the protected influence "${zero.bone}" a share of ${zero.share}, which is 0 on the 6-decimal weight grid; required a share that can be written as a positive binding — a protected influence is never dropped silently`,
+      );
+    }
+    entries = entries.filter((e) => e !== zero);
+    tally.sharesDroppedOnGrid++;
+    normalise();
+  }
+  for (;;) {
+    const out: Binding[] = [];
+    let others = 0;
+    entries.forEach((e, k) => {
+      const w = k === entries.length - 1 ? r6(1 - others) : r6(e.share);
+      others += w;
+      out.push({ bone: e.bone, weight: w });
+    });
+    const last = out[out.length - 1];
+    if (last.weight > 0) return out;
+    // The closing share fell to 0 or below on the grid: it is a share the grid cannot hold.
+    const lastEntry = entries[entries.length - 1];
+    if (guarded.has(lastEntry.bone)) {
+      throw new Stop(
+        'invalid-input',
+        'REDUCE_PROTECTED_INFLUENCE_BELOW_GRID',
+        `${where} closes the protected influence "${lastEntry.bone}" at ${last.weight} on the 6-decimal weight grid; required a positive binding`,
+      );
+    }
+    entries = entries.slice(0, -1);
+    tally.sharesDroppedOnGrid++;
+    normalise();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// the deform keys (P18)
+// ---------------------------------------------------------------------------
+
+/** Deform-array start of each vertex and its width: two per vertex unweighted, two per influence weighted. */
+function layoutOf(weights: readonly Binding[][] | null, count: number): { start: number[]; width: number[] } {
+  const start: number[] = [];
+  const width: number[] = [];
+  let at = 0;
+  for (let v = 0; v < count; v++) {
+    const w = weights === null ? 2 : 2 * weights[v].length;
+    start.push(at);
+    width.push(w);
+    at += w;
+  }
+  return { start, width };
+}
+
+/** The source vertices a `vertices` run writes into. */
+function verticesUnder(key: Extract<DeformKeyInput, { kind: 'vertices' }>, layout: { start: number[]; width: number[] }): number[] {
+  const out: number[] = [];
+  const end = key.offset + key.vertices.length;
+  layout.start.forEach((s, v) => {
+    if (s < end && s + layout.width[v] > key.offset) out.push(v);
+  });
+  return out;
+}
+
+function deformName(animation: string, ref: AttachmentRef, key: number, time: number): string {
+  return `animation "${animation}", slot "${ref.slot}", attachment "${ref.attachment}"${ref.skin === null ? '' : ` (skin "${ref.skin}")`}, key ${key} (t ${time})`;
+}
+
+/** Refused before any work (P18): a deform timeline keyed on a linked mesh, whose own keys this remap does not carry; and a run past the source's array (A35). */
+function checkDeformBeforeWork(input: MeshReductionInput): void {
+  const layout = layoutOf(input.source.weights, input.source.points.length);
+  const length = layout.start.length === 0 ? 0 : layout.start[layout.start.length - 1] + layout.width[layout.width.length - 1];
+  for (const tl of input.deform) {
+    const linked = !sameRef(tl.attachment, input.attachment);
+    tl.keys.forEach((key, k) => {
+      if (linked && key.kind !== 'setup') {
+        throw new Stop(
+          'unsupported-topology',
+          'REDUCE_DEFORM_INDEXED',
+          `attachment ${nameOf(input.attachment)}: ${deformName(tl.animation, tl.attachment, k, key.time)} is keyed on a linked mesh of ${nameOf(input.attachment)}; required keys on the source attachment only — a linked mesh's own vertex-indexed keys are not remapped by this operation, and a linked mesh that inherits plays the source's remapped keys`,
+        );
+      }
+      if (key.kind === 'vertices' && key.offset + key.vertices.length > length) {
+        refuse(
+          'REDUCE_INPUT_MISSING',
+          `attachment ${nameOf(input.attachment)}: ${deformName(tl.animation, tl.attachment, k, key.time)} writes deform-array entries ${key.offset}..${key.offset + key.vertices.length - 1}; required within the source's ${length} (A35)`,
+        );
+      }
+    });
+  }
+}
+
+/** The vertices runs on the source that cover a source vertex — what an insertion beside it would sit under. */
+function keyedSourceVertices(input: MeshReductionInput): Map<number, { animation: string; ref: AttachmentRef; key: number; time: number }> {
+  const layout = layoutOf(input.source.weights, input.source.points.length);
+  const out = new Map<number, { animation: string; ref: AttachmentRef; key: number; time: number }>();
+  for (const tl of input.deform) {
+    tl.keys.forEach((key, k) => {
+      if (key.kind !== 'vertices') return;
+      for (const v of verticesUnder(key, layout)) if (!out.has(v)) out.set(v, { animation: tl.animation, ref: tl.attachment, key: k, time: key.time });
+    });
+  }
+  return out;
+}
+
+/**
+ * Every deform key carried onto the result's vertex order. A `vertices` run is
+ * rewritten entry by entry onto the vertex and influence it addressed; entries
+ * of a removed vertex are dropped and reported; the gaps a reorder opens are
+ * zero, which is what the format reads outside a run anyway. Refused by name: a
+ * weighted keyed vertex whose binding list is not the same list in the same
+ * order in the result — its pairs would land on other influences.
+ */
+function remapDeform(input: MeshReductionInput, result: SourceMesh, indexMap: Array<number | null>): { remapped: RemappedDeformKey[]; reevaluated: DeformKeyRef[] } {
+  const before = layoutOf(input.source.weights, input.source.points.length);
+  const after = layoutOf(result.weights, result.points.length);
+  const remapped: RemappedDeformKey[] = [];
+  const reevaluated: DeformKeyRef[] = [];
+  for (const tl of input.deform) {
+    tl.keys.forEach((key, k) => {
+      if (key.kind === 'transform') {
+        reevaluated.push({ animation: tl.animation, attachment: tl.attachment, key: k, time: key.time });
+        return;
+      }
+      if (key.kind !== 'vertices') return;
+      const placed = new Map<number, number>();
+      const dropped = new Set<number>();
+      key.vertices.forEach((value, j) => {
+        const at = key.offset + j;
+        let v = 0;
+        while (v + 1 < before.start.length && before.start[v + 1] <= at) v++;
+        const within = at - before.start[v];
+        const r = indexMap[v];
+        if (r === null) {
+          dropped.add(v);
+          return;
+        }
+        if (input.source.weights !== null) {
+          const was = input.source.weights[v].map((b) => b.bone).join(',');
+          const now = result.weights![r].map((b) => b.bone).join(',');
+          if (was !== now) {
+            throw new Stop(
+              'unsupported-topology',
+              'REDUCE_DEFORM_INDEXED',
+              `attachment ${nameOf(input.attachment)}: ${deformName(tl.animation, tl.attachment, k, key.time)} keys source vertex ${v}, weighted [${was}], which the result binds [${now}]; required the same influences in the same order, so each pair of the run still lands on its influence — a weighted keyed mesh whose influence layout changes is not remapped`,
+            );
+          }
+        }
+        placed.set(after.start[r] + within, value);
+      });
+      const positions = [...placed.keys()].sort((a, b) => a - b);
+      const offset = positions.length === 0 ? 0 : positions[0];
+      const vertices: number[] = [];
+      if (positions.length > 0) for (let at = offset; at <= positions[positions.length - 1]; at++) vertices.push(placed.get(at) ?? 0);
+      remapped.push({ animation: tl.animation, attachment: tl.attachment, key: k, time: key.time, offset, vertices, droppedVertices: [...dropped].sort((a, b) => a - b) });
+    });
+  }
+  return { remapped, reevaluated };
+}
+
+// ---------------------------------------------------------------------------
+// the composed operation's shared state
+// ---------------------------------------------------------------------------
+
+interface Run {
+  input: MeshReductionInput;
+  who: string;
+  work: Work;
+  boneRank: Map<string, number>;
+  sourceTurn: number;
+  sourceHull: Array<[number, number]>;
+  /** Steps tried so far, refinement insertions and removal attempts alike. */
+  steps: number;
+  tally: Tally;
+  keyed: Map<number, { animation: string; ref: AttachmentRef; key: number; time: number }>;
+  protectedVertices: Set<number>;
+  protectedEdges: Array<[number, number]>;
+  sourceEdges: Set<string>;
+}
+
+/** A measurement of a canonical mesh against the result's full contract. */
+function measureAgainstTargets(run: Run, mesh: SourceMesh, id: string): MeshQualityReport {
+  const { input } = run;
+  const targets = input.targets;
+  const measureInput: MeshMeasureInput = {
+    id,
+    attachment: input.attachment,
+    art: input.art,
+    source: mesh,
+    targets: { artFit: targets.artFit, maxBoundaryDeviation: targets.maxBoundaryDeviation, ...(targets.minAngle === undefined ? {} : { minAngle: targets.minAngle }), regions: targets.regions },
+    referenceHull: run.sourceHull,
+    minArtSamples: input.minArtSamples,
+    regionArtSamples: input.regionArtSamples,
+    protect: input.protect,
+    influences: input.influences,
+    boneOrder: input.boneOrder,
+    preset: input.preset,
+  };
+  return measureMeshQuality(measureInput);
+}
+
+/** The order constraints are named in when several fail on one step: structure, then shape, then art, then density. */
+const BLOCKING_ORDER = ['MQ_ORIENTATION', 'MQ_DEGENERATE', 'MQ_BOUNDARY_DEVIATION', 'MQ_COVERAGE', 'MQ_OVERSHOOT', 'MQ_UNDERCUT', 'MQ_MIN_ANGLE', 'MQ_MAX_EDGE', 'MQ_TRANSITION'];
+
+function rowName(row: MeasureRow): string {
+  const region = row.object.region === null ? '' : `[${row.object.region}]`;
+  if (row.state === 'fail') return `${row.code}${region}: ${row.value} against ${row.bound!.op} ${row.bound!.value}`;
+  return `${row.code}${region}: ${row.state} — ${row.reason ?? ''}`;
+}
+
+/**
+ * The first required row that is not `pass`, in `BLOCKING_ORDER`, or null when
+ * every one passes. A row is required exactly when its bound is declared; the
+ * overshoot row gated is the 8-connected one (P12).
+ */
+function firstBlockingRow(report: MeshQualityReport): MeasureRow | null {
+  const rows = report.candidates[0]?.geometry?.rows ?? [];
+  const required = (r: MeasureRow): boolean => {
+    if (r.code === 'MQ_OVERSHOOT') return r.art?.connectivity === 8;
+    if (r.code === 'MQ_MIN_ANGLE') return r.bound !== null;
+    if (r.code === 'MQ_HOLES' || r.code === 'MQ_ISLANDS' || r.code === 'MQ_TRACE_DEVIATION' || r.code === 'MQ_FILL_DISTANCE') return false;
+    return true;
+  };
+  for (const code of BLOCKING_ORDER) {
+    const hit = rows.find((r) => r.code === code && required(r) && r.state !== 'pass');
+    if (hit !== undefined) return hit;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// refinement (§5)
+// ---------------------------------------------------------------------------
+
+/** Where to split edge a–b for `region`: its midpoint when that is in the region or its band, else the point inside them nearest the midpoint. */
+function splitPoint(a: Pt, b: Pt, region: RefinementRegion): Pt | null {
+  const at = (t: number): Pt => [r6(a[0] + (b[0] - a[0]) * t), r6(a[1] + (b[1] - a[1]) * t)];
+  const usable = (q: Pt): boolean => inRegionOrBand(q, region) && !(q[0] === a[0] && q[1] === a[1]) && !(q[0] === b[0] && q[1] === b[1]);
+  if (usable(at(0.5))) return at(0.5);
+  // The parameters where the inside of the region or its band can begin or end: crossings of the
+  // polygon's edges and the feet of its vertices; the inside point nearest the midpoint is among them.
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  const len2 = dx * dx + dy * dy;
+  const ts = new Set<number>();
+  const poly = region.polygon;
+  for (let i = 0; i < poly.length; i++) {
+    const c = poly[i];
+    const d = poly[(i + 1) % poly.length];
+    ts.add(Math.max(0, Math.min(1, ((c[0] - a[0]) * dx + (c[1] - a[1]) * dy) / len2)));
+    const ex = d[0] - c[0];
+    const ey = d[1] - c[1];
+    const den = dx * ey - dy * ex;
+    if (Math.abs(den) > 1e-12) {
+      const t = ((c[0] - a[0]) * ey - (c[1] - a[1]) * ex) / den;
+      const u = ((c[0] - a[0]) * dy - (c[1] - a[1]) * dx) / den;
+      if (t >= 0 && t <= 1 && u >= -1e-9 && u <= 1 + 1e-9) ts.add(t);
+    }
+  }
+  const candidates = [...ts].filter((t) => t > 0 && t < 1 && usable(at(t))).sort((p, q) => Math.abs(p - 0.5) - Math.abs(q - 0.5) || p - q);
+  if (candidates.length > 0) return at(candidates[0]);
+  // A point of the edge in the band only at an endpoint: halve towards it from the midpoint.
+  for (const end of [0, 1]) {
+    if (!inRegionOrBand(end === 0 ? a : b, region)) continue;
+    let t = 0.5;
+    for (let i = 0; i < SPLIT_SEARCH_STEPS; i++) {
+      t = (t + end) / 2;
+      if (usable(at(t))) return at(t);
+    }
+  }
+  return null;
+}
+
+/** Add a vertex at `p` with what interpolation gives it, refusing it under a deform run (P18). */
+function addVertex(run: Run, p: Pt): number {
+  const got = interpolate(p, run.input, run.boneRank, run.tally, run.who);
+  const src = run.input.source;
+  for (let k = 0; k < 3; k++) {
+    const corner = src.triangles[got.sourceTriangle * 3 + k];
+    const key = run.keyed.get(corner);
+    if (key !== undefined) {
+      throw new Stop(
+        'unsupported-topology',
+        'REDUCE_DEFORM_INDEXED',
+        `${run.who}: ${deformName(key.animation, key.ref, key.key, key.time)} keys source vertex ${corner}, and the refinement would insert a vertex at (${p[0]}, ${p[1]}) in source triangle ${got.sourceTriangle} beside it, under the run; required no insertion under a vertices run — the inserted vertex has no offset in any key`,
+      );
+    }
+  }
+  const id = run.work.pos.length;
+  run.work.pos.push(p);
+  run.work.uv.push(got.uv);
+  if (run.work.weights !== null) run.work.weights.push(got.weights!);
+  run.work.alive.push(true);
+  run.work.sourceTriangle.set(id, got.sourceTriangle);
+  return id;
+}
+
+/** Split the edge between working ids a and b at `p`: each triangle on it becomes two, winding kept. */
+function splitEdge(run: Run, a: number, b: number, p: Pt): void {
+  const m = addVertex(run, p);
+  const next: Array<[number, number, number]> = [];
+  for (const tri of run.work.triangles) {
+    const i = tri.indexOf(a);
+    const j = tri.indexOf(b);
+    if (i === -1 || j === -1) {
+      next.push(tri);
+      continue;
+    }
+    // Rotate so the edge is the triangle's first two corners, in its own winding.
+    const r = (j - i + 3) % 3 === 1 ? i : j;
+    const x = tri[r];
+    const y = tri[(r + 1) % 3];
+    const c = tri[(r + 2) % 3];
+    next.push([x, m, c], [m, y, c]);
+  }
+  run.work.triangles = next;
+}
+
+/** Insert `p` into the working triangle that holds it: on an edge, that edge is split; inside, the triangle becomes three. */
+function insertPoint(run: Run, p: Pt): boolean {
+  const { work } = run;
+  for (const tri of work.triangles) {
+    const l = barycentric(p, work.pos[tri[0]], work.pos[tri[1]], work.pos[tri[2]]);
+    if (l === null || Math.min(...l) < -1e-9) continue;
+    const onEdge = l.findIndex((v) => Math.abs(v) <= 1e-9);
+    if (onEdge !== -1) {
+      splitEdge(run, tri[(onEdge + 1) % 3], tri[(onEdge + 2) % 3], p);
+      return true;
+    }
+    const m = addVertex(run, p);
+    work.triangles = work.triangles.flatMap((t): Array<[number, number, number]> => (t === tri ? [[tri[0], tri[1], m], [tri[1], tri[2], m], [tri[2], tri[0], m]] : [t]));
+    return true;
+  }
+  return false;
+}
+
+type PhaseEnd =
+  | { kind: 'done' }
+  | { kind: 'budget' }
+  | { kind: 'stuck'; constraint: string };
+
+/**
+ * Refine the working mesh until every region's `MQ_MAX_EDGE` and
+ * `MQ_TRANSITION` that the refinement can act on passes. One insertion per
+ * measurement: the first failing region row in report order has its worst edge
+ * split. A band no edge lies in leaves `MQ_TRANSITION` not-measurable (B1's
+ * definition) and is not something an insertion is aimed at.
+ */
+function refineRegions(run: Run): PhaseEnd {
+  const regions = new Map(run.input.targets.regions.map((r) => [r.name, r]));
+  if (regions.size === 0) return { kind: 'done' };
+  for (;;) {
+    const canon = canonicalise(run.work, run.sourceTurn, run.boneRank);
+    const report = measureAgainstTargets(run, canon.mesh, 'refinement');
+    const rows = report.candidates[0]?.geometry?.rows ?? [];
+    const target = rows.find((r) => (r.code === 'MQ_MAX_EDGE' || r.code === 'MQ_TRANSITION') && r.state === 'fail') ?? rows.find((r) => r.code === 'MQ_MAX_EDGE' && r.state === 'not-measurable' && (r.reason ?? '').includes('no triangle edge meets'));
+    if (target === undefined) return { kind: 'done' };
+    if (run.steps >= run.input.budget.maxCandidates) return { kind: 'budget' };
+    run.steps++;
+    const region = regions.get(target.object.region!)!;
+    if (target.state === 'not-measurable') {
+      const p: Pt = [r6(region.polygon[0][0]), r6(region.polygon[0][1])];
+      if (!insertPoint(run, p)) return { kind: 'stuck', constraint: `${rowName(target)} (the refinement found no triangle holding the region's first vertex)` };
+      continue;
+    }
+    const [ra, rb] = target.worst!.at.edge!;
+    const a = canon.order[ra];
+    const b = canon.order[rb];
+    // An end outside the region and its band further beyond the band than the edge's own bound: every
+    // split keeps an edge from a vertex inside them to that end, so no insertion P16 allows can meet it.
+    for (const [end, id] of [[ra, a], [rb, b]] as const) {
+      const at = run.work.pos[id];
+      if (inRegionOrBand(at, region)) continue;
+      const beyond = distanceToBoundary(at, region.polygon) - region.transition;
+      if (beyond > target.bound!.value) {
+        return {
+          kind: 'stuck',
+          constraint: `${rowName(target)} (vertex ${end} of edge ${ra}–${rb} lies ${r6(beyond)} px beyond region "${region.name}"'s ${region.transition} px band, further than the edge's bound ${target.bound!.value}: an edge from inside the region and its band to it stays over the bound, and the refinement inserts only inside them — P16)`,
+        };
+      }
+    }
+    const p = splitPoint(run.work.pos[a], run.work.pos[b], region);
+    if (p === null) return { kind: 'stuck', constraint: `${rowName(target)} (the refinement found no point of edge ${ra}–${rb} strictly between its ends inside region "${region.name}" or its band)` };
+    splitEdge(run, a, b, p);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// reduction (§1, §6)
+// ---------------------------------------------------------------------------
+
+/** One removal tried: the working triangles after it and the edges it added, or the structural reason it cannot be made. */
+function removalOf(work: Work, v: number): { triangles: Array<[number, number, number]>; added: Array<[number, number]> } | { blocked: string } {
+  const star = work.triangles.filter((t) => t.includes(v));
+  const next = new Map<number, number>();
+  const incoming = new Set<number>();
+  for (const t of star) {
+    const k = t.indexOf(v);
+    const a = t[(k + 1) % 3];
+    const b = t[(k + 2) % 3];
+    if (next.has(a) || incoming.has(b)) return { blocked: `retriangulation: vertex ${v}'s triangles do not form one fan` };
+    next.set(a, b);
+    incoming.add(b);
+  }
+  const heads = [...next.keys()].filter((a) => !incoming.has(a));
+  const boundary = heads.length === 1;
+  if (heads.length > 1) return { blocked: `retriangulation: vertex ${v}'s triangles do not form one fan` };
+  let at = boundary ? heads[0] : Math.min(...next.keys());
+  const ring = [at];
+  for (;;) {
+    const to = next.get(at);
+    if (to === undefined || to === ring[0]) break;
+    ring.push(to);
+    at = to;
+    if (ring.length > next.size + 1) return { blocked: `retriangulation: vertex ${v}'s link does not close` };
+  }
+  if (ring.length !== (boundary ? next.size + 1 : next.size)) return { blocked: `retriangulation: vertex ${v}'s triangles do not form one fan` };
+  const rest = work.triangles.filter((t) => !t.includes(v));
+  const fresh: Array<[number, number, number]> = [];
+  if (ring.length >= 3) {
+    const poly = ring.map((id): [number, number] => [work.pos[id][0], work.pos[id][1]]);
+    if (findSelfIntersection(poly) !== null) return { blocked: `retriangulation: the hole vertex ${v} leaves is not a strictly simple polygon` };
+    let tris: number[];
+    try {
+      tris = earClip(poly);
+    } catch (err) {
+      if (!(err instanceof MeshError)) throw err;
+      return { blocked: `retriangulation: the hole vertex ${v} leaves does not ear-clip (${err.message})` };
+    }
+    for (let i = 0; i < tris.length; i += 3) fresh.push([ring[tris[i]], ring[tris[i + 1]], ring[tris[i + 2]]]);
+  } else if (!boundary) {
+    return { blocked: `retriangulation: vertex ${v} has fewer than three neighbours` };
+  }
+  const old = new Set<string>();
+  for (const t of work.triangles) for (let k = 0; k < 3; k++) old.add(edgeKey(t[k], t[(k + 1) % 3]));
+  const added: Array<[number, number]> = [];
+  const seen = new Set<string>();
+  for (const t of fresh) {
+    for (let k = 0; k < 3; k++) {
+      const key = edgeKey(t[k], t[(k + 1) % 3]);
+      if (old.has(key) || seen.has(key)) continue;
+      seen.add(key);
+      added.push([t[k], t[(k + 1) % 3]]);
+    }
+  }
+  return { triangles: [...rest, ...fresh], added };
+}
+
+/** L1 difference of two weight vectors over the bones they name. */
+function weightJump(work: Work, a: number, b: number): number {
+  if (work.weights === null) return 0;
+  const shares = new Map<string, number>();
+  for (const bnd of work.weights[a]) shares.set(bnd.bone, (shares.get(bnd.bone) ?? 0) + bnd.weight);
+  for (const bnd of work.weights[b]) shares.set(bnd.bone, (shares.get(bnd.bone) ?? 0) - bnd.weight);
+  let sum = 0;
+  for (const v of shares.values()) sum += Math.abs(v);
+  return sum;
+}
+
+/**
+ * Remove surviving source vertices in ascending source index, pass after pass,
+ * taking a step only when every structural condition and every required row
+ * holds after it. Ends when a pass takes no step, or when the budget is spent.
+ */
+function removeVertices(run: Run): PhaseEnd {
+  const { work, input } = run;
+  let lastBlock = '';
+  for (;;) {
+    let taken = 0;
+    let tried = 0;
+    for (let v = 0; v < work.nSource; v++) {
+      if (!work.alive[v] || run.protectedVertices.has(v)) continue;
+      if (run.steps >= input.budget.maxCandidates) return { kind: 'budget' };
+      run.steps++;
+      tried++;
+      const block = tryRemoval(run, v);
+      if (block === null) taken++;
+      else lastBlock = `${block}, removing source vertex ${v}`;
+    }
+    if (taken === 0) {
+      if (tried === 0) lastBlock = 'protect: every surviving source vertex is protected (protect.hull, protect.vertices, protect.edges, protect.regionBoundaries or a weightJump edge)';
+      return { kind: 'stuck', constraint: lastBlock };
+    }
+  }
+}
+
+/** One removal: null when it was taken, else the constraint that blocked it. */
+function tryRemoval(run: Run, v: number): string | null {
+  const { work, input } = run;
+  const step = removalOf(work, v);
+  if ('blocked' in step) return step.blocked;
+  const jump = input.protect.weightJump;
+  if (jump !== null) {
+    for (const [a, b] of step.added) {
+      if (a < work.nSource && b < work.nSource && run.sourceEdges.has(edgeKey(a, b))) continue;
+      const d = weightJump(work, a, b);
+      if (d > jump) return `weightJump (b): the new edge ${a}–${b} joins weight vectors ${r6(d)} apart, over ${jump}`;
+    }
+  }
+  const was = { triangles: work.triangles };
+  work.triangles = step.triangles;
+  work.alive[v] = false;
+  const undo = (): void => {
+    work.triangles = was.triangles;
+    work.alive[v] = true;
+  };
+  const edges = new Set<string>();
+  for (const t of work.triangles) for (let k = 0; k < 3; k++) edges.add(edgeKey(t[k], t[(k + 1) % 3]));
+  for (const [a, b] of run.protectedEdges) {
+    if (!edges.has(edgeKey(a, b))) {
+      undo();
+      return `protect (a): the protected source edge ${a}–${b} is no longer an edge`;
+    }
+  }
+  let canon: Canonical;
+  try {
+    canon = canonicalise(work, run.sourceTurn, run.boneRank);
+  } catch (err) {
+    if (!(err instanceof MeshError)) throw err;
+    undo();
+    return `outline: ${err.message}`;
+  }
+  const blocking = firstBlockingRow(measureAgainstTargets(run, canon.mesh, 'candidate'));
+  if (blocking !== null) {
+    undo();
+    return rowName(blocking);
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// the operation
+// ---------------------------------------------------------------------------
+
+/**
+ * Reduce one mesh towards the caller's targets, refining it first where a
+ * region asks for density — §1, §5 and §6 of docs/MESH_REDUCTION.md, geometry
+ * only. Throws a `MeshReductionError` for a malformed input (a missing or
+ * out-of-range field, a threshold, a mask or a UV out of range); reports
+ * everything else, with exactly one `Termination`:
+ *
+ * - `invalid-input`: the source fails its own art bounds
+ *   (`REDUCE_SOURCE_FAILS_ITS_ART_BOUNDS`, `sourceBounds` only — correction 3),
+ *   a region is refused (`REGION_*`), full coverage is asked of a source that
+ *   leaves an art island untouched (`REDUCE_ISLAND_UNREACHED`), or an inserted
+ *   vertex's protected influences cannot be written
+ *   (`REDUCE_PROTECTED_INFLUENCES_OVER_CAP`, `REDUCE_PROTECTED_INFLUENCE_BELOW_GRID`);
+ * - `unsupported-topology`: the source is not one loop
+ *   (`REDUCE_SOURCE_NOT_ONE_LOOP`) or a deform key cannot be carried
+ *   (`REDUCE_DEFORM_INDEXED`);
+ * - `budget-exhausted`: `budget.maxCandidates` steps were tried — the result is
+ *   returned when it meets every required bound, and none is when it does not;
+ * - `no-further-valid-reduction`: a pass took no step, naming what blocked the
+ *   last one. A local stop: nothing here says the result is the smallest.
+ */
+export function reduceMesh(input: MeshReductionInput): MeshReductionResult {
+  validateReduction(input);
+  const who = `attachment ${nameOf(input.attachment)}`;
+  const src = input.source;
+  const sourceHull: Array<[number, number]> = src.points.slice(0, Math.max(0, src.hull)).map(([x, y]): [number, number] => [x, y]);
+
+  // The source, measured against its own admissibility bounds (correction 3) — this is also what refuses a
+  // malformed art, mesh, region list or sample floor, by measureMeshQuality's own codes.
+  const admit = measureMeshQuality({
+    id: 'source',
+    attachment: input.attachment,
+    art: input.art,
+    source: src,
+    targets: { artFit: input.sourceBounds, maxBoundaryDeviation: null, regions: input.targets.regions },
+    referenceHull: null,
+    minArtSamples: input.minArtSamples,
+    regionArtSamples: input.regionArtSamples,
+    protect: input.protect,
+    influences: input.influences,
+    boneOrder: input.boneOrder,
+    preset: input.preset,
+  });
+  const effective = effectiveOf(input, admit.effective, sourceHull);
+  const sourceCounts = admit.sourceCounts;
+  const noMesh = (termination: Termination): MeshReductionResult => ({
+    mesh: null,
+    report: reportOf(effective, sourceCounts, { id: 'result', counts: null, geometry: null, motion: null, accepted: false }, termination),
+  });
+  if (admit.termination !== null) return noMesh(admit.termination);
+
+  try {
+    const admitRows = admit.candidates[0]?.geometry?.rows ?? [];
+    for (const row of admitRows) {
+      if (row.state === 'refused') {
+        const reason = row.reason ?? '';
+        const code = reason.slice(0, reason.indexOf(':'));
+        throw new Stop('invalid-input', code, reason.slice(code.length + 2));
+      }
+    }
+    for (const code of ['MQ_ORIENTATION', 'MQ_DEGENERATE', 'MQ_COVERAGE', 'MQ_OVERSHOOT', 'MQ_UNDERCUT']) {
+      const row = admitRows.find((r) => r.code === code && (code !== 'MQ_OVERSHOOT' || r.art?.connectivity === 8));
+      if (row !== undefined && row.state !== 'pass') {
+        const found = row.state === 'fail' ? `${row.value} against ${row.bound!.op} ${row.bound!.value}` : `${row.state} (${row.reason ?? ''})`;
+        throw new Stop(
+          'invalid-input',
+          'REDUCE_SOURCE_FAILS_ITS_ART_BOUNDS',
+          `${who}: the source's ${code} is ${found}; required the source to pass its own art bounds (sourceBounds) and its own winding — a source that does not is not a reference to reduce from (correction 3)`,
+        );
+      }
+    }
+    checkIslands(input, who);
+    checkDeformBeforeWork(input);
+
+    const boneRank = new Map((input.boneOrder ?? []).map((b, i) => [b, i]));
+    const work: Work = {
+      nSource: src.points.length,
+      pos: src.points.map((p): Pt => p),
+      uv: src.points.map((_, i): [number, number] => [src.uvs[i * 2], src.uvs[i * 2 + 1]]),
+      weights: src.weights === null ? null : src.weights.map((v) => v.map((b) => ({ bone: b.bone, weight: b.weight }))),
+      alive: src.points.map(() => true),
+      triangles: [],
+      sourceTriangle: new Map(),
+    };
+    for (let i = 0; i + 2 < src.triangles.length; i += 3) work.triangles.push([src.triangles[i], src.triangles[i + 1], src.triangles[i + 2]]);
+    const sourceEdges = new Set<string>();
+    for (const t of work.triangles) for (let k = 0; k < 3; k++) sourceEdges.add(edgeKey(t[k], t[(k + 1) % 3]));
+    const run: Run = {
+      input,
+      who,
+      work,
+      boneRank,
+      sourceTurn: Math.sign(signedArea(sourceHull)),
+      sourceHull,
+      steps: 0,
+      tally: { sharesDroppedOnGrid: 0, sharesPruned: 0 },
+      keyed: keyedSourceVertices(input),
+      ...protectionOf(input, work, sourceEdges),
+      sourceEdges,
+    };
+
+    const refined = refineRegions(run);
+    if (refined.kind === 'budget') return noMesh({ reason: 'budget-exhausted', candidatesTried: run.steps, budget: input.budget.maxCandidates, result: 'none-met-the-targets' });
+    const startCanon = canonicalise(work, run.sourceTurn, boneRank);
+    const startBlock = firstBlockingRow(measureAgainstTargets(run, startCanon.mesh, 'start'));
+    let termination: Termination;
+    if (startBlock !== null) {
+      const constraint = refined.kind === 'stuck' ? refined.constraint : rowName(startBlock);
+      termination = { reason: 'no-further-valid-reduction', candidatesTried: run.steps, blockingConstraint: `${constraint} — before any removal: the refined source does not meet its targets, so no step from it can` };
+    } else {
+      const reduced = removeVertices(run);
+      termination =
+        reduced.kind === 'budget'
+          ? { reason: 'budget-exhausted', candidatesTried: run.steps, budget: input.budget.maxCandidates, result: 'best-meeting-every-bound' }
+          : { reason: 'no-further-valid-reduction', candidatesTried: run.steps, blockingConstraint: reduced.kind === 'stuck' ? reduced.constraint : '' };
+    }
+    return finish(run, effective, sourceCounts, termination);
+  } catch (err) {
+    if (err instanceof Stop) return noMesh({ reason: err.reason, code: err.code, detail: err.detail });
+    throw err;
+  }
+}
+
+/** §4: full coverage asked of a source that touches no pixel of some art island is refused, never met by deleting art. */
+function checkIslands(input: MeshReductionInput, who: string): void {
+  if (input.targets.artFit.minCoverage !== 1) return;
+  const { mask, threshold, frame } = input.art;
+  const bits = artOf(mask, threshold);
+  const { label, sizes } = labelIslands(bits, mask.width, mask.height);
+  const onGrid = input.source.points.map(([x, y]): [number, number] => [x * frame.pageScale, y * frame.pageScale]);
+  const covered = rasteriseTriangles(onGrid, input.source.triangles, mask.width, mask.height);
+  const touched = new Set<number>();
+  for (let i = 0; i < label.length; i++) if (label[i] && covered[i]) touched.add(label[i]);
+  for (let island = 1; island <= sizes.length; island++) {
+    if (touched.has(island) || sizes[island - 1] === 0) continue;
+    const at = label.indexOf(island);
+    throw new Stop(
+      'invalid-input',
+      'REDUCE_ISLAND_UNREACHED',
+      `${who}: the art island of ${sizes[island - 1]} pixel(s) at (${at % mask.width}, ${Math.floor(at / mask.width)}) has no pixel the source covers, and targets.artFit.minCoverage is 1; required a source that reaches every island when full coverage is asked — art is never deleted to meet a bound (§4)`,
+    );
+  }
+}
+
+/** The vertices no step may remove and the source edges every result must keep (§6, conditions (a) and (b)). */
+function protectionOf(input: MeshReductionInput, work: Work, sourceEdges: Set<string>): { protectedVertices: Set<number>; protectedEdges: Array<[number, number]> } {
+  const p = input.protect;
+  const vertices = new Set<number>(p.vertices);
+  if (p.hull) for (let v = 0; v < input.source.hull; v++) vertices.add(v);
+  const edges: Array<[number, number]> = p.edges.map(([a, b]): [number, number] => [a, b]);
+  if (p.weightJump !== null) {
+    for (const key of [...sourceEdges].sort()) {
+      const [a, b] = key.split(',').map(Number);
+      if (weightJump(work, a, b) > p.weightJump) edges.push([a, b]);
+    }
+  }
+  for (const [a, b] of edges) {
+    vertices.add(a);
+    vertices.add(b);
+  }
+  for (const name of p.regionBoundaries) {
+    const region = input.targets.regions.find((r) => r.name === name)!;
+    input.source.points.forEach((pt, v) => {
+      if (distanceToBoundary(pt, region.polygon) <= ON_BOUNDARY) vertices.add(v);
+    });
+  }
+  return { protectedVertices: vertices, protectedEdges: edges };
+}
+
+/** The result, canonical, with its deform keys carried and its own measurement as the report's one candidate. */
+function finish(run: Run, effective: EffectiveSettings, sourceCounts: MeshCounts | null, termination: Termination): MeshReductionResult {
+  const { input, work } = run;
+  const canon = canonicalise(work, run.sourceTurn, run.boneRank);
+  const indexMap: Array<number | null> = [];
+  for (let v = 0; v < work.nSource; v++) indexMap.push(work.alive[v] ? canon.indexOf.get(v)! : null);
+  const inserted = [...canon.indexOf.entries()].filter(([id]) => id >= work.nSource).map(([, r]) => r).sort((a, b) => a - b);
+  let deform: { remapped: RemappedDeformKey[]; reevaluated: DeformKeyRef[] };
+  try {
+    deform = remapDeform(input, canon.mesh, indexMap);
+  } catch (err) {
+    if (err instanceof Stop) {
+      return { mesh: null, report: reportOf(effective, sourceCounts, { id: 'result', counts: null, geometry: null, motion: null, accepted: false }, { reason: err.reason, code: err.code, detail: err.detail }) };
+    }
+    throw err;
+  }
+  const measured = measureAgainstTargets(run, canon.mesh, 'result');
+  const candidate = measured.candidates[0];
+  const changes: ReductionChanges = {
+    removedVertices: indexMap.filter((r) => r === null).length,
+    insertedVertices: inserted.length,
+    sharesDroppedOnGrid: run.tally.sharesDroppedOnGrid,
+    sharesPruned: run.tally.sharesPruned,
+    deformRemapped: deform.remapped.map((d) => ({ animation: d.animation, attachment: d.attachment, key: d.key, droppedVertices: d.droppedVertices })),
+    deformReevaluated: deform.reevaluated.map((d) => ({ animation: d.animation, attachment: d.attachment, key: d.key })),
+    linkedMeshes: input.linkedMeshes,
+  };
+  const counts = candidate.counts!;
+  const mesh: ReducedMesh = {
+    ...canon.mesh,
+    edges: meshEdges(canon.mesh.points.length, canon.mesh.triangles, canon.mesh.hull),
+    indexMap,
+    inserted,
+    linkedMeshes: input.linkedMeshes,
+    deform,
+    counts,
+  };
+  return { mesh, report: reportOf(effective, sourceCounts, { ...candidate, changes }, termination) };
+}
+
+function reportOf(effective: EffectiveSettings, sourceCounts: MeshCounts | null, candidate: CandidateReport, termination: Termination): MeshQualityReport {
+  return {
+    spec: 'mesh-quality-report/1',
+    operation: 'reduce',
+    effective,
+    poser: null,
+    motionRequired: false,
+    sourceCounts,
+    reference: null,
+    candidates: [candidate],
+    termination,
+  };
+}
+
+/** Correction 1: the reduction's inputs echoed with their structure — the measurement's echo, with what a reduction adds. */
+function effectiveOf(input: MeshReductionInput, measured: EffectiveSettings, sourceHull: Array<[number, number]>): EffectiveSettings {
+  const fit = (f: ArtFitBounds): ArtFitBounds => ({ minCoverage: f.minCoverage, maxOvershoot: f.maxOvershoot, maxUndercut: f.maxUndercut });
+  return {
+    ...measured,
+    sourceBounds: fit(input.sourceBounds),
+    targets: input.targets,
+    referenceHull: sourceHull,
+    budget: { maxCandidates: input.budget.maxCandidates },
+  };
+}