rig-c 2.29.0 → 2.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-c",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "description": "AI-authored Spine 2D rigging and animation, verified before it is written. rigc compiles a rig spec into Spine 4.3 skeleton data, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Output imports into the Spine editor. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/mesh.ts

@@ -50,9 +50,11 @@ import type { ModelBinding, ModelVertices } from './model.ts';
 // two form an import cycle: safe only because neither reads the other's
 // bindings while it is being evaluated — every use is inside a function.
 // The reduction (`reduceMesh`, stage B2 of #1224) sits in the same cycle, by
-// the same rule.
+// the same rule. So does the skinning residual and its envelope helper
+// (`src/meshskinning.ts`, issue #1294), which the measurement reads.
 export * from './meshquality.ts';
 export * from './meshreduce.ts';
+export * from './meshskinning.ts';
 
 export interface MeshSpecInput {
   /** Polygon in part-local pixels, y down, in manifest order. */

package/src/meshcarriers.ts

@@ -0,0 +1,167 @@
+/**
+ * Where a UV sample lies in a mesh's UV triangulation — §3 and correction 4 of
+ * docs/MESH_REDUCTION.md, the common domain two triangulations of one
+ * attachment are compared on.
+ *
+ * `uvCarriers` was written for the motion comparison (`src/meshcompare.ts`,
+ * issue #1230), which still re-exports it from `rig-c/meshcompare` where it is
+ * promised. It lives here, in a module that links no poser, because the
+ * skinning residual (`src/meshskinning.ts`, issue #1294) reads the same carriers
+ * from `rig-c/mesh`, which is geometry-only (§0, P1): one definition of "the
+ * triangle that carries this UV" for both, so the residual and the motion row
+ * it is compared with can never disagree about which triangle a sample is in.
+ *
+ * Pure: no clock, no randomness, no runtime.
+ */
+import { MeshReductionError } from './mesh.ts';
+import { areaBand, triangleAreas } from './areaband.ts';
+
+/** `pointInTriangle`'s epsilon in `src/mesh.ts`, applied to each barycentric coordinate. */
+export const CONTAINS = 1e-9;
+
+function refuse(code: string, message: string): never {
+  throw new MeshReductionError(code, message);
+}
+
+/** A sample's carrier: the UV triangle that contains it, its three vertex indices and the sample's barycentric coordinates there. */
+export interface Carrier {
+  triangle: number;
+  corners: [number, number, number];
+  bary: [number, number, number];
+}
+
+/**
+ * Each sample's carrier in one mesh's UV triangulation — §3 and correction 4.
+ * Throws `COMPARE_UV_CARRIER_NOT_UNIQUE` for a sample two triangles carry
+ * other than across a vertex or edge they share.
+ */
+export function uvCarriers(uvs: readonly number[], triangles: readonly number[], samples: ReadonlyArray<{ uv: [number, number] }>, who: string): Array<Carrier | null> {
+  const areas = triangleAreas(uvs, triangles);
+  const band = areaBand(areas, uvs);
+  const live: number[] = [];
+  const boxes: number[] = [];
+  for (let t = 0; t < areas.length; t++) {
+    if (Math.abs(areas[t]) <= band) continue;
+    live.push(t);
+    const xs = [uvs[triangles[t * 3] * 2], uvs[triangles[t * 3 + 1] * 2], uvs[triangles[t * 3 + 2] * 2]];
+    const ys = [uvs[triangles[t * 3] * 2 + 1], uvs[triangles[t * 3 + 1] * 2 + 1], uvs[triangles[t * 3 + 2] * 2 + 1]];
+    boxes.push(Math.min(...xs), Math.min(...ys), Math.max(...xs), Math.max(...ys));
+  }
+  const u = (v: number): number => uvs[v * 2];
+  const w = (v: number): number => uvs[v * 2 + 1];
+  // Issue #1295: the samples bucketed on a uniform grid, so each live triangle is tested only against the samples in
+  // the cells its box (with the containment slack) overlaps — every (sample, triangle) pair the box test could pass is
+  // still tested, by the same `carrierIn`, and each sample's hits are gathered in ascending triangle index, the order
+  // a scan of every live triangle per sample gathered them in. The carriers are that scan's, value for value; what
+  // changes is that the work no longer grows with samples × triangles.
+  const n = samples.length;
+  const hits: Array<Carrier[] | null> = new Array(n).fill(null);
+  if (n > 0 && live.length > 0) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const s of samples) {
+      minX = Math.min(minX, s.uv[0]);
+      minY = Math.min(minY, s.uv[1]);
+      maxX = Math.max(maxX, s.uv[0]);
+      maxY = Math.max(maxY, s.uv[1]);
+    }
+    const G = Math.max(1, Math.min(1024, Math.ceil(Math.sqrt(n / 4))));
+    const cw = (maxX - minX) / G || 1;
+    const ch = (maxY - minY) / G || 1;
+    const cellX = (x: number): number => Math.min(G - 1, Math.max(0, Math.floor((x - minX) / cw)));
+    const cellY = (y: number): number => Math.min(G - 1, Math.max(0, Math.floor((y - minY) / ch)));
+    const start = new Int32Array(G * G + 1);
+    const cellOf = new Int32Array(n);
+    samples.forEach((s, j) => {
+      cellOf[j] = cellY(s.uv[1]) * G + cellX(s.uv[0]);
+      start[cellOf[j] + 1]++;
+    });
+    for (let c = 0; c < G * G; c++) start[c + 1] += start[c];
+    const order = new Int32Array(n);
+    const fill = start.slice(0, G * G);
+    for (let j = 0; j < n; j++) order[fill[cellOf[j]]++] = j;
+    const slack = 1e-9;
+    live.forEach((t, k) => {
+      const [x0, y0, x1, y1] = [boxes[k * 4], boxes[k * 4 + 1], boxes[k * 4 + 2], boxes[k * 4 + 3]];
+      const cy0 = cellY(y0 - slack);
+      const cy1 = cellY(y1 + slack);
+      const cx0 = cellX(x0 - slack);
+      const cx1 = cellX(x1 + slack);
+      for (let cy = cy0; cy <= cy1; cy++) {
+        for (let cx = cx0; cx <= cx1; cx++) {
+          const c = cy * G + cx;
+          for (let q = start[c]; q < start[c + 1]; q++) {
+            const j = order[q];
+            const hit = carrierIn(samples[j].uv[0], samples[j].uv[1], x0, y0, x1, y1, triangles[t * 3], triangles[t * 3 + 1], triangles[t * 3 + 2], u, w, t);
+            if (hit !== null) (hits[j] ??= []).push(hit);
+          }
+        }
+      }
+    });
+  }
+  return samples.map((s, j) => resolveCarriers(s.uv[0], s.uv[1], hits[j] ?? [], who));
+}
+
+/**
+ * Whether the UV triangle i0, i1, i2 (`t`, its box x0..x1, y0..y1) carries the sample at (px, py), and where: the
+ * carrier, or null. The one containment test — `uvCarriers` and the reduction's carried residual (issue #1295) both
+ * read it, so a sample is in a triangle by one arithmetic.
+ */
+export function carrierIn(
+  px: number,
+  py: number,
+  x0: number,
+  y0: number,
+  x1: number,
+  y1: number,
+  i0: number,
+  i1: number,
+  i2: number,
+  u: (v: number) => number,
+  v: (v: number) => number,
+  t: number,
+): Carrier | null {
+  const slack = 1e-9;
+  if (px < x0 - slack || py < y0 - slack || px > x1 + slack || py > y1 + slack) return null;
+  const ax = u(i0);
+  const ay = v(i0);
+  const bx = u(i1) - ax;
+  const by = v(i1) - ay;
+  const cx = u(i2) - ax;
+  const cy = v(i2) - ay;
+  const qx = px - ax;
+  const qy = py - ay;
+  const det = bx * cy - cx * by;
+  const l1 = (qx * cy - cx * qy) / det;
+  const l2 = (bx * qy - qx * by) / det;
+  const l0 = 1 - l1 - l2;
+  if (l0 < -CONTAINS || l1 < -CONTAINS || l2 < -CONTAINS) return null;
+  return { triangle: t, corners: [i0, i1, i2], bary: [l0, l1, l2] };
+}
+
+/**
+ * The carrier of a sample from every triangle that contains it: none, the one, or — several — the first when they all
+ * meet there at a shared vertex or edge; else `COMPARE_UV_CARRIER_NOT_UNIQUE` (correction 4).
+ */
+export function resolveCarriers(px: number, py: number, hits: readonly Carrier[], who: string): Carrier | null {
+  if (hits.length === 0) return null;
+  if (hits.length === 1) return hits[0];
+  // Several carriers are one hit only across a vertex or an edge they all share: the sample's support — the corners
+  // it does not sit at zero weight on — is then the same vertex indices in each, and the carried point is theirs.
+  const support = (c: Carrier): string =>
+    c.corners
+      .filter((_v, k) => c.bary[k] > CONTAINS)
+      .sort((a, b) => a - b)
+      .join(',');
+  const first = support(hits[0]);
+  const shared = first.split(',').length <= 2 && hits.every((c) => support(c) === first);
+  if (!shared) {
+    refuse(
+      'COMPARE_UV_CARRIER_NOT_UNIQUE',
+      `${who}: the sample at uv (${px}, ${py}) lies in ${hits.length} UV triangles — ${hits.map((c) => `triangle ${c.triangle} (vertices ${c.corners.join(', ')})`).join(' and ')} — that do not meet there at a shared vertex or edge; required one carrier per sample (correction 4: overlapping or folded UV triangles would carry it by an arbitrary one)`,
+    );
+  }
+  return hits[0];
+}

package/src/meshcompare.ts

@@ -100,6 +100,7 @@ import {
   type WorstSample,
 } from './meshquality.ts';
 import { areaBand, stretchSingularValues, triangleAreas } from './areaband.ts';
+import { uvCarriers, type Carrier } from './meshcarriers.ts';
 import { CoreInputError, readModel, underNoSkin, underSkin, type CompiledDocument } from './core/index.ts';
 import { poseRawAnimationEach, poseRawSetup, type RawPose } from './core/raw.ts';
 import { sampleTime } from './core/animation.ts';
@@ -178,9 +179,6 @@ export type ComparePlant = 'amplitude-not-carried' | 'null-read-as-left-out' | '
 // fixed tolerances — the tree's own
 // ---------------------------------------------------------------------------
 
-/** `pointInTriangle`'s epsilon in `src/mesh.ts`, applied to each barycentric coordinate. */
-const CONTAINS = 1e-9;
-
 /** §3 *Independent evidence* (a): the rows a reference is refused on — its art fit against its own mask, and only that. */
 const REFERENCE_ART_FIT: readonly string[] = ['MQ_COVERAGE', 'MQ_OVERSHOOT', 'MQ_UNDERCUT'];
 
@@ -585,6 +583,9 @@ function poseBuild(doc: CompiledDocument, refs: readonly AttachmentRef[], frames
 // §3 — the samples and their carriers
 // ---------------------------------------------------------------------------
 
+/** Promised on `rig-c/meshcompare` since issue #1230; defined in `src/meshcarriers.ts` since issue #1294, which the skinning residual shares. */
+export { uvCarriers };
+
 interface Sample {
   uv: [number, number];
   /** Part-local drawing px, y down — where a region's polygon is read. */
@@ -594,12 +595,6 @@ interface Sample {
   vertex: number | null;
 }
 
-interface Carrier {
-  triangle: number;
-  corners: [number, number, number];
-  bary: [number, number, number];
-}
-
 interface MeshOf {
   uvs: number[];
   triangles: number[];
@@ -607,68 +602,6 @@ interface MeshOf {
   weights: SourceMesh['weights'];
 }
 
-/**
- * Each sample's carrier in one mesh's UV triangulation — §3 and correction 4.
- * Throws `COMPARE_UV_CARRIER_NOT_UNIQUE` for a sample two triangles carry
- * other than across a vertex or edge they share.
- */
-export function uvCarriers(uvs: readonly number[], triangles: readonly number[], samples: ReadonlyArray<{ uv: [number, number] }>, who: string): Array<Carrier | null> {
-  const areas = triangleAreas(uvs, triangles);
-  const band = areaBand(areas, uvs);
-  const live: number[] = [];
-  const boxes: number[] = [];
-  for (let t = 0; t < areas.length; t++) {
-    if (Math.abs(areas[t]) <= band) continue;
-    live.push(t);
-    const xs = [uvs[triangles[t * 3] * 2], uvs[triangles[t * 3 + 1] * 2], uvs[triangles[t * 3 + 2] * 2]];
-    const ys = [uvs[triangles[t * 3] * 2 + 1], uvs[triangles[t * 3 + 1] * 2 + 1], uvs[triangles[t * 3 + 2] * 2 + 1]];
-    boxes.push(Math.min(...xs), Math.min(...ys), Math.max(...xs), Math.max(...ys));
-  }
-  return samples.map((s) => {
-    const [px, py] = s.uv;
-    const hits: Carrier[] = [];
-    live.forEach((t, k) => {
-      const slack = 1e-9;
-      if (px < boxes[k * 4] - slack || py < boxes[k * 4 + 1] - slack || px > boxes[k * 4 + 2] + slack || py > boxes[k * 4 + 3] + slack) return;
-      const i0 = triangles[t * 3];
-      const i1 = triangles[t * 3 + 1];
-      const i2 = triangles[t * 3 + 2];
-      const ax = uvs[i0 * 2];
-      const ay = uvs[i0 * 2 + 1];
-      const bx = uvs[i1 * 2] - ax;
-      const by = uvs[i1 * 2 + 1] - ay;
-      const cx = uvs[i2 * 2] - ax;
-      const cy = uvs[i2 * 2 + 1] - ay;
-      const qx = px - ax;
-      const qy = py - ay;
-      const det = bx * cy - cx * by;
-      const l1 = (qx * cy - cx * qy) / det;
-      const l2 = (bx * qy - qx * by) / det;
-      const l0 = 1 - l1 - l2;
-      if (l0 < -CONTAINS || l1 < -CONTAINS || l2 < -CONTAINS) return;
-      hits.push({ triangle: t, corners: [i0, i1, i2], bary: [l0, l1, l2] });
-    });
-    if (hits.length === 0) return null;
-    if (hits.length === 1) return hits[0];
-    // Several carriers are one hit only across a vertex or an edge they all share: the sample's support — the corners
-    // it does not sit at zero weight on — is then the same vertex indices in each, and the carried point is theirs.
-    const support = (c: Carrier): string =>
-      c.corners
-        .filter((_v, k) => c.bary[k] > CONTAINS)
-        .sort((a, b) => a - b)
-        .join(',');
-    const first = support(hits[0]);
-    const shared = first.split(',').length <= 2 && hits.every((c) => support(c) === first);
-    if (!shared) {
-      refuse(
-        'COMPARE_UV_CARRIER_NOT_UNIQUE',
-        `${who}: the sample at uv (${px}, ${py}) lies in ${hits.length} UV triangles — ${hits.map((c) => `triangle ${c.triangle} (vertices ${c.corners.join(', ')})`).join(' and ')} — that do not meet there at a shared vertex or edge; required one carrier per sample (correction 4: overlapping or folded UV triangles would carry it by an arbitrary one)`,
-      );
-    }
-    return hits[0];
-  });
-}
-
 /** The point a carrier puts the sample at over one pose's world vertices. */
 function carried(c: Carrier, world: readonly number[]): [number, number] {
   const [i0, i1, i2] = c.corners;

package/src/meshquality.ts

@@ -71,6 +71,7 @@ import {
 } from './mesh.ts';
 import { areaBand, triangleAreas } from './areaband.ts';
 import { allocationContrast, boundaryNecessityOnce, deformLoad, gradeMax, minAngleP10, type AllocationArt, type AllocationPlant } from './meshallocation.ts';
+import { skinningEchoOf, skinningResidual, validateSkinning, type ReductionSkinning, type SkinningDetail, type SkinningEcho, type SkinningPlant, type SkinningResidualInput } from './meshskinning.ts';
 import { artRastersOf, type ArtRasters, type CoverageReading, type OutlineMemo, type RegionEdgeReading, type SilhouetteReading, type StepRasters } from './meshrasters.ts';
 import { cropToSpineY } from './transform.ts';
 
@@ -146,6 +147,16 @@ export interface ReductionTargets {
   minAngle?: number;
   /** Local density requirements — §5. */
   regions: RefinementRegion[];
+  /**
+   * Issue #1295 (§7 mechanism 1, the reducer half) — opt-in. Left out = no step reads a residual and the call is the
+   * one it was before the field existed, byte for byte. Set, every removal, boundary run and triangulation post-pass is
+   * taken only when `MQ_SKINNING_RESIDUAL` of its result against the call's own `source` — the original, never a
+   * previous step — is within `maxResidual` and every other required row passes; refinement insertions are not vetoed
+   * one by one, and the refined mesh is held to it before any removal. The result's measurement carries the row.
+   * `null` declares it absent (no row read by a step, the result's row `not-measurable` saying so); anything else that
+   * is not `{ envelope, maxResidual }` in full is refused `REDUCE_INPUT_MISSING` naming its path, before any work.
+   */
+  skinning?: ReductionSkinning | null;
 }
 
 /** P16/P17: a local density requirement over a closed polygon. */
@@ -369,6 +380,16 @@ export interface MeshMeasureInput {
    * `null` art bound is declared absent, #1257). It declares no bound: every allocation row stays `undeclared`.
    */
   motionAmplitude?: MotionAmplitude | null;
+  /**
+   * Issue #1294 (§7, mechanism 1): the skinning-envelope residual of this mesh — the candidate — against the original
+   * source it was made from, under a declared envelope (`SkinningResidualInput`, `src/meshskinning.ts`). Left out, it
+   * is not asked for: no `MQ_SKINNING_RESIDUAL` row and no echo, so the report is the one written without the field,
+   * byte for byte. `null` declares it absent: the row is `not-measurable` saying so, and the echo is `null`. Set, the
+   * row is measured over §3's samples at `art.threshold` and is required when `maxResidual` is a number; a source or an
+   * envelope the measurement cannot read refuses the row by name. Anything that is not a `SkinningResidualInput` in
+   * full is refused `REDUCE_INPUT_MISSING` naming its path, before any work.
+   */
+  skinning?: SkinningResidualInput | null;
 }
 
 /**
@@ -442,6 +463,8 @@ export interface MeasureRow {
   motion?: MotionRowDetail;
   /** The five allocation rows only (issue #1280): what the value is a reading of, and what it was read from. */
   allocation?: AllocationDetail;
+  /** `MQ_SKINNING_RESIDUAL` when measured (issue #1294): the source, the samples, the worst sample's terms and the contract's own figures. */
+  skinning?: SkinningDetail;
 }
 
 /** Issue #1280: an allocation row's own fields. Written on those five rows, measured or not, and on no other. */
@@ -610,6 +633,8 @@ export interface EffectiveSettings {
   retriangulate?: 'delaunay';
   /** A reduction's `removalOrder`, echoed when the input set it (issue #1283); absent otherwise — the order was ascending source index. */
   removalOrder?: 'deformation-load';
+  /** A measurement's `skinning`, echoed when the input set it — `null` included (issue #1294): the source by id and digest. Absent otherwise. */
+  skinning?: SkinningEcho | null;
 }
 
 export interface MeshCounts {
@@ -863,6 +888,7 @@ function validateInput(input: MeshMeasureInput): void {
     refuse('REDUCE_INPUT_MISSING', `${who}: preset is not { name, version }; required that, or null`);
   }
   validateMotionAmplitude(who, input.motionAmplitude);
+  validateSkinning(who, input.skinning);
 }
 
 /**
@@ -1503,6 +1529,15 @@ export function measureMeshQualityPlanted(input: MeshMeasureInput, plant: Alloca
   return measureValidated(input, artRastersOf(input.art), null, plant);
 }
 
+/**
+ * `measureMeshQuality` with a fault planted in the skinning residual or its report (issue #1294, `SkinningPlant` in
+ * `src/meshskinning.ts`) — the `mesh-compare` suite's negative controls. Internal, as `measureMeshQualityWith` is.
+ */
+export function measureMeshQualitySkinningPlanted(input: MeshMeasureInput, plant: SkinningPlant): MeshQualityReport {
+  validateInput(input);
+  return measureValidated(input, artRastersOf(input.art), null, null, plant);
+}
+
 /**
  * `measureMeshQuality` over art rasters the caller already holds
  * (`src/meshrasters.ts`) — what `reduceMesh` calls for every measurement of
@@ -1612,12 +1647,12 @@ function checkArtRasters(input: MeshMeasureInput, rasters: ArtRasters): void {
 }
 
 /** The measurement proper, over an input `validateInput` accepted and rasters taken from its art. */
-function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: StepRasters | null, plant: AllocationPlant | null): MeshQualityReport {
+function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: StepRasters | null, plant: AllocationPlant | null, skinningPlant: SkinningPlant | null = null): MeshQualityReport {
   rasters.tally.uses++;
   const { attachment, art, source, targets } = input;
   const { mask, threshold, frame } = art;
   const scale = frame.pageScale;
-  const effective = effectiveOf(input);
+  const effective = effectiveOf(input, skinningPlant);
   const report = (sourceCounts: MeshCounts | null, candidate: CandidateReport, termination: Termination | null): MeshQualityReport => ({
     spec: MESH_QUALITY_REPORT_SPEC,
     operation: 'measure',
@@ -1654,6 +1689,9 @@ function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: S
   // --- allocation rows (issue #1280): undeclared or not-measurable, never required ------------
   if (plant !== 'omit-rows') rows.push(...allocationRows(input, outline, rasters, steps, plant));
 
+  // --- the skinning residual (issue #1294): only when the input asked for it ------------------
+  if (input.skinning !== undefined || skinningPlant === 'row-when-unset') rows.push(skinningRow(input, rasters, skinningPlant));
+
   // --- raster rows ---------------------------------------------------------
   const w = mask.width;
   const h = mask.height;
@@ -1805,6 +1843,53 @@ function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: S
   return report(counts, { id: input.id, counts, geometry, motion: null, accepted }, null);
 }
 
+/**
+ * `MQ_SKINNING_RESIDUAL` (issue #1294, `src/meshskinning.ts`): a geometry row in drawing px, required when
+ * `skinning.maxResidual` is a number. `null` for the field reads `not-measurable` saying it was declared absent;
+ * a refusal of the source or the envelope is a `refused` row whose reason opens with its code. The samples are §3's:
+ * art pixel centres at `art.threshold` and the source hull's UVs.
+ */
+function skinningRow(input: MeshMeasureInput, rasters: ArtRasters, plant: SkinningPlant | null): Built {
+  const { attachment, art } = input;
+  const spec: RowSpec = { code: 'MQ_SKINNING_RESIDUAL', unit: 'px', region: null, attachment };
+  const skinning = input.skinning;
+  if (skinning === undefined || skinning === null) {
+    const why =
+      skinning === null
+        ? `attachment ${nameOf(attachment)}: skinning is null — the residual is declared absent, so there is no source or envelope to measure against`
+        : `attachment ${nameOf(attachment)}: skinning was not set`;
+    return unmeasuredRow(spec, 'not-measurable', why, false);
+  }
+  const bound = skinning.maxResidual === null ? null : { op: '<=' as const, value: skinning.maxResidual };
+  const reading = skinningResidual(
+    {
+      attachment,
+      frame: art.frame,
+      artBits: rasters.artBits(),
+      maskWidth: art.mask.width,
+      maskHeight: art.mask.height,
+      minArtSamples: input.minArtSamples,
+      threshold: art.threshold,
+      candidate: input.source,
+      skinning,
+    },
+    plant,
+  );
+  const sampling = { domain: `art pixel centres at alpha >= ${art.threshold} and the source's hull UVs, on the region UV square, carried by the source's and this mesh's UV triangles`, count: reading.samples };
+  const artField = { threshold: art.threshold, connectivity: null, samples: reading.art };
+  if (reading.state !== 'measured') {
+    const built = unmeasuredRow(spec, reading.state, reading.reason, bound !== null);
+    built.row.art = artField;
+    built.row.sampling = sampling;
+    return built;
+  }
+  const built = measuredRow(spec, reading.value, bound, reading.worst, true);
+  built.row.art = artField;
+  built.row.sampling = sampling;
+  built.row.skinning = reading.detail;
+  return built;
+}
+
 /** What each allocation row is a reading of — `AllocationDetail.reading`, one fixed sentence per code. */
 const ALLOCATION_READINGS: Record<string, string> = {
   MQ_GRADE:
@@ -2223,7 +2308,7 @@ function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon:
 // the echo, and the document's text
 // ---------------------------------------------------------------------------
 
-function effectiveOf(input: MeshMeasureInput): EffectiveSettings {
+function effectiveOf(input: MeshMeasureInput, skinningPlant: SkinningPlant | null = null): EffectiveSettings {
   const { art } = input;
   return {
     preset: input.preset,
@@ -2251,6 +2336,7 @@ function effectiveOf(input: MeshMeasureInput): EffectiveSettings {
     schedule: null,
     budget: null,
     ...(input.motionAmplitude === undefined ? {} : { motionAmplitude: input.motionAmplitude }),
+    ...(input.skinning === undefined ? (skinningPlant === 'echo-when-unset' ? { skinning: null } : {}) : { skinning: skinningEchoOf(input.skinning) }),
   };
 }
 
@@ -2283,6 +2369,11 @@ function targetsJson(t: ReductionTargets | MeasureTargets | null): Json {
   const out: { [key: string]: Json } = { artFit: fitJson(t.artFit), maxBoundaryDeviation: t.maxBoundaryDeviation };
   if (t.minAngle !== undefined) out.minAngle = t.minAngle;
   out.regions = t.regions.map(regionJson);
+  // Issue #1295: a reduction's `targets.skinning`, echoed when the input set it — `null` included — and never otherwise.
+  if ('skinning' in t && t.skinning !== undefined) {
+    const k = t.skinning;
+    out.skinning = k === null ? null : { envelope: { reference: k.envelope.reference, bones: k.envelope.bones.map((b) => ({ bone: b.bone, linear: b.linear, pivot: pair(b.pivot), translation: b.translation })) }, maxResidual: k.maxResidual };
+  }
   return out;
 }
 
@@ -2344,6 +2435,7 @@ function effectiveJson(e: EffectiveSettings): Json {
     ...(e.motionAmplitude === undefined ? {} : { motionAmplitude: amplitudeJson(e.motionAmplitude) }),
     ...(e.retriangulate === undefined ? {} : { retriangulate: e.retriangulate }),
     ...(e.removalOrder === undefined ? {} : { removalOrder: e.removalOrder }),
+    ...(e.skinning === undefined ? {} : { skinning: skinningEchoJson(e.skinning) }),
   };
 }
 
@@ -2388,9 +2480,40 @@ function rowJson(r: MeasureRow): Json {
   if (r.sampling !== undefined) out.sampling = { domain: r.sampling.domain, count: r.sampling.count };
   if (r.motion !== undefined) out.motion = motionDetailJson(r.motion);
   if (r.allocation !== undefined) out.allocation = allocationDetailJson(r.allocation);
+  if (r.skinning !== undefined) out.skinning = skinningDetailJson(r.skinning);
   return out;
 }
 
+function deformJson(t: DeformTimelineInput): Json {
+  return {
+    animation: t.animation,
+    attachment: attachmentJson(t.attachment),
+    keys: t.keys.map((k): Json => (k.kind === 'vertices' ? { time: k.time, kind: k.kind, offset: k.offset, vertices: [...k.vertices] } : { time: k.time, kind: k.kind })),
+  };
+}
+
+function skinningEchoJson(e: SkinningEcho | null): Json {
+  if (e === null) return null;
+  return {
+    source: { id: e.source.id, digest: e.source.digest },
+    envelope: { reference: e.envelope.reference, bones: e.envelope.bones.map((b) => ({ bone: b.bone, linear: b.linear, pivot: pair(b.pivot), translation: b.translation })) },
+    maxResidual: e.maxResidual,
+    deform: e.deform.map(deformJson),
+  };
+}
+
+function skinningDetailJson(d: SkinningDetail): Json {
+  return {
+    reading: d.reading,
+    source: { id: d.source.id, digest: d.source.digest },
+    reference: d.reference,
+    samples: { measured: d.samples.measured, uncarried: { source: d.samples.uncarried.source.map(pair), candidate: d.samples.uncarried.candidate.map(pair) } },
+    worst: d.worst === null ? null : { covariance: d.worst.covariance, lever: d.worst.lever, bones: d.worst.bones.map((b) => ({ bone: b.bone, covariance: b.covariance, lever: b.lever })) },
+    weightField: { l1: d.weightField.l1, lInf: d.weightField.lInf },
+    setup: { vertexGap: d.setup.vertexGap, vertexSlack: pair(d.setup.vertexSlack), sampleGap: d.setup.sampleGap, weightSumGap: d.setup.weightSumGap },
+  };
+}
+
 function allocationDetailJson(a: AllocationDetail): Json {
   const out: { [key: string]: Json } = { reading: a.reading };
   if (a.contrast !== undefined) {