spine-rigc 0.16.0 → 0.18.0

package/src/compile.ts

@@ -17,9 +17,22 @@
  * Determinism is a contract, not a habit: `validate` re-runs this and compares
  * the two emits byte for byte (assertion A18).
  */
-import { basename, dirname, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { readPngInfo } from './png.ts';
+import {
+  DEPTH_TONE_IDENTITY,
+  DepthError,
+  checkTone,
+  checkZScale,
+  depthDigest,
+  sampleLevel,
+  toneLevel,
+  turnCeiling,
+  type DepthMap,
+  type DepthNear,
+  type DepthTone,
+} from './depth.ts';
 import { CompileError, NotImplementedError } from './errors.ts';
 import { parseJsonWithPosition } from './json-position.ts';
 import { parseMotionSpec } from './motion.ts';
@@ -42,9 +55,12 @@ import {
   type RigRegionAttachment,
   type RigSpec,
   type RigVertexGeometry,
+  type RigDepthMap,
+  type RigSoftRegion,
 } from './rig.ts';
 import {
   buildContourMesh,
+  buildGridMesh,
   buildRibbonMesh,
   buildRingMesh,
   checkHullOrder,
@@ -57,6 +73,7 @@ import {
   type MeshBoneRef,
   type MeshFitReport,
   type MeshGeometry,
+  type MeshVertexWeight,
 } from './mesh.ts';
 import { Plate, readPlate } from '../tools/plate.ts';
 import {
@@ -76,6 +93,7 @@ import {
   normaliseDegrees,
   screenToSpineDegrees,
   toBoneLocal,
+  toBoneLocalVector,
   toWorld,
   TransformError,
   type BoneTransform,
@@ -1246,6 +1264,9 @@ export function compile(opts: CompileOptions): CompileResult {
   for (const skinName of skinNames) tableFor(skinName);
   const meshBones = new Set<string>();
   const meshes: CompileResult['meshes'] = [];
+  // `skin/slot/attachment` -> per-vertex z, for the attachments that named a
+  // depth map. Read at deform-key time; never emitted. See `AttachmentContext`.
+  const attachmentDepths = new Map<string, number[]>();
 
   for (const rigSlot of rig.slots) {
     const part = partBySlot.get(rigSlot.name);
@@ -1335,6 +1356,9 @@ export function compile(opts: CompileOptions): CompileResult {
           meshes,
           slotName: rigSlot.name,
           anchorBone: rigSlot.bone,
+          skinName,
+          imagesDir,
+          depths: attachmentDepths,
           slotNames: new Set(rig.slots.map((s) => s.name)),
         });
       }
@@ -1424,6 +1448,7 @@ export function compile(opts: CompileOptions): CompileResult {
     slotNames: new Set(rig.slots.map((s) => s.name)),
     pathSlots,
     animationNames: new Set(Object.keys(motion.animations ?? {})),
+    animationDurations: new Map(Object.entries(motion.animations ?? {}).map(([name, anim]) => [name, anim.duration])),
   };
   // Read as the raw records they are on disk: `buildRigConstraint` checks every
   // field itself, because a spec that came off a file has whatever the author
@@ -1665,7 +1690,10 @@ export function compile(opts: CompileOptions): CompileResult {
           motion,
           animName,
           anim.duration,
-          deformGeometryOf(attachment, at),
+          {
+            ...deformGeometryOf(attachment, at, bones, transforms),
+            depth: attachmentDepths.get(`${skinName}/${track.slot}/${track.attachment}`) ?? null,
+          },
           deformTransforms,
         );
         for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
@@ -1930,6 +1958,25 @@ interface AttachmentContext {
   meshes: CompileResult['meshes'];
   slotName: string;
   anchorBone: string;
+  /** Which skin this attachment is being built for — half of a `depths` key. */
+  skinName: string;
+  /**
+   * Where a file the spec names is resolved from. A depth map is read from here
+   * and never packed, so it is the one input path that does not go through
+   * `images`.
+   */
+  imagesDir: string;
+  /**
+   * Per-vertex `z` for the attachments that named a depth map, keyed by
+   * `skin/slot/attachment`.
+   *
+   * ⭐ It rides beside the emitted attachment rather than on it. A `z` written
+   * into the mesh would be a field the Spine format has no room for — the
+   * parser drops what it does not know, so it would survive exactly until the
+   * round trip and then vanish — and the whole point of this table is to be
+   * read by `evaluateDeformTransform` at key time and never emitted at all.
+   */
+  depths: Map<string, number[]>;
   /** Every slot the rig declares — a clipping attachment's `end` resolves here. */
   slotNames: Set<string>;
 }
@@ -2580,6 +2627,7 @@ function buildGeneratedMesh(
   ctx: AttachmentContext,
 ): SpineMeshAttachment {
   if (generator.kind === 'contour') return buildContourAttachment(att, generator, placeholder, where, ctx);
+  if (generator.kind === 'grid') return buildGridAttachment(att, generator, placeholder, where, ctx);
   const controls = generator.kind === 'ring' ? generator.controls : generator.chain;
   const refFor = (name: string): MeshBoneRef => {
     const index = ctx.bones.findIndex((b) => b.name === name);
@@ -2638,6 +2686,433 @@ function buildGeneratedMesh(
   return out;
 }
 
+/**
+ * Read a depth map, check it against the part it claims to describe, and put a
+ * `z` on every vertex.
+ *
+ * ## The three refusals, and why each one is a refusal
+ *
+ * **A size that is not the part's.** The map is sampled in part-local pixels,
+ * so a sheet of a different size is a different coordinate system; sampling it
+ * anyway would read the right shape from the wrong place and produce a turn
+ * that is subtly, plausibly wrong everywhere.
+ *
+ * **A colour image.** A depth map is one channel. Silently taking red from an
+ * RGB file works right up until somebody hands over a normal map or a tinted
+ * preview, and then the part turns by whatever the red channel happened to say.
+ *
+ * **A vertex the map does not cover.** This is the one that is easy to miss and
+ * ruins the result. A `contour` mesh's vertices are ALL on the silhouette, and
+ * the outline is pushed `margin` pixels OUTSIDE it — while a depth sheet is
+ * usually cut to the art's own alpha. Sample naively and every vertex reads the
+ * sheet's transparent background, the whole rim takes the background depth, and
+ * the silhouette folds away from the turn. Nothing about that is detectable
+ * downstream: the arithmetic is correct and the numbers are plausible. So a
+ * sheet that carries an alpha channel is held to it, and the fix — dilate the
+ * sheet past the mesh margin — is named in the message.
+ *
+ * A sheet with no alpha channel covers its whole grid by construction and the
+ * third check has nothing to test; what the background level means is then the
+ * author's statement, and `range` in the report is where it shows up.
+ */
+function sampleMeshDepth(
+  spec: NonNullable<Extract<NonNullable<RigMeshAttachment['generator']>, { kind: 'contour' }>['depth']>,
+  kind: 'contour' | 'grid',
+  points: ReadonlyArray<readonly [number, number]>,
+  /** The mesh's own triangle list, for the turn ceiling. */
+  triangles: ReadonlyArray<number>,
+  /**
+   * A part-local pixel to the BIND space this mesh's vertices are emitted in —
+   * the same composition `encodeWeightedVertices` applies, handed in rather than
+   * rebuilt so the two cannot diverge.
+   *
+   * 🚨 The ceiling has to be taken in bind space and in no other. A deform
+   * offset is authored there, so a rotated slot bone MIXES the two axes: a
+   * ceiling measured in part-aligned pixels would report the yaw limit of a
+   * turn nobody is taking. It is also scale-sensitive — a ratio of an area to
+   * an area with a depth substituted into it — so part pixels have to reach the
+   * units `z` is already in before it is taken.
+   */
+  toBind: (px: number, py: number) => readonly [number, number],
+  partWidth: number,
+  partHeight: number,
+  where: string,
+  ctx: AttachmentContext,
+): {
+  z: number[];
+  /** The tone-curved 0..1 nearness per vertex, which `bind` thresholds. */
+  nearness: number[];
+  summary: NonNullable<CompileResult['meshes'][number]['depth']>;
+} {
+  if (typeof spec.image !== 'string' || spec.image.length === 0) {
+    throw new CompileError(`${where}: the depth block has no "image"; it is the sheet to sample, relative to the rig's images directory`);
+  }
+  if (spec.near !== 'white' && spec.near !== 'black') {
+    throw new CompileError(
+      `${where}: the depth block says "near": ${JSON.stringify(spec.near)}; it is "white" or "black". Both ` +
+        'conventions are in use, and a sheet read with the wrong one turns the part inside out with every gate green.',
+    );
+  }
+  const tone: DepthTone = {
+    gamma: spec.gamma ?? DEPTH_TONE_IDENTITY.gamma,
+    contrast: spec.contrast ?? DEPTH_TONE_IDENTITY.contrast,
+    bias: spec.bias ?? DEPTH_TONE_IDENTITY.bias,
+  };
+  try {
+    checkTone(tone, where);
+    checkZScale(spec.zScale, where);
+  } catch (err) {
+    if (err instanceof DepthError) throw new CompileError(err.message);
+    throw err;
+  }
+
+  const { map, cover, opaqueEverywhere } = readGreySheet(spec.image, 'depth', partWidth, partHeight, where, ctx);
+
+  // Every texel a bilinear tap touches has to be covered, not just the nearest
+  // one: a vertex half a pixel outside the sheet blends real depth with the
+  // background and lands somewhere neither states.
+  const uncovered: number[] = [];
+  if (!opaqueEverywhere) {
+    const cx = (i: number): number => (i < 0 ? 0 : i > partWidth - 1 ? partWidth - 1 : i);
+    const cy = (j: number): number => (j < 0 ? 0 : j > partHeight - 1 ? partHeight - 1 : j);
+    for (let v = 0; v < points.length; v++) {
+      const x0 = Math.floor(points[v][0] - 0.5);
+      const y0 = Math.floor(points[v][1] - 0.5);
+      let covered = true;
+      for (const [dx, dy] of [[0, 0], [1, 0], [0, 1], [1, 1]] as const) {
+        if (cover[cy(y0 + dy) * partWidth + cx(x0 + dx)] !== 255) covered = false;
+      }
+      if (!covered) uncovered.push(v);
+    }
+  }
+  if (uncovered.length > 0) {
+    const first = uncovered[0];
+    // The two topologies run out of sheet for different reasons, and a message
+    // that explains the wrong one sends the author to the wrong fix.
+    const why =
+      kind === 'contour'
+        ? 'A contour mesh puts every vertex ON the silhouette and pushes it out by the margin, so a sheet cut to ' +
+          'the art stops short of every one of them. Dilate the sheet past the mesh margin, or lower the margin.'
+        : 'A grid spans the whole part window, corners included, while a sheet is usually cut to the art — so the ' +
+          'lattice reaches past it wherever the art does not fill the window. Dilate the sheet to the window, or ' +
+          'state "us"/"vs" that keep the lattice inside the art.';
+    throw new CompileError(
+      `${where}: the depth map "${spec.image}" does not cover ${uncovered.length} of the mesh's ${points.length} ` +
+        `vertices — the first is vertex ${first} at (${points[first][0]}, ${points[first][1]}). ${why} ` +
+        'Sampling anyway would give those vertices the sheet\'s background depth and fold them away from the turn.',
+    );
+  }
+
+  const z: number[] = [];
+  const nearness: number[] = [];
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (const [x, y] of points) {
+    const n = toneLevel(sampleLevel(map, x, y), spec.near as DepthNear, tone);
+    const d = n * spec.zScale;
+    nearness.push(n);
+    z.push(d);
+    if (d < lo) lo = d;
+    if (d > hi) hi = d;
+  }
+  return {
+    z,
+    nearness,
+    summary: {
+      image: spec.image,
+      digest: depthDigest(map),
+      near: spec.near,
+      zScale: spec.zScale,
+      tone,
+      range: [r6(lo), r6(hi)],
+      ceiling: turnCeiling(
+        points.map(([px, py]) => toBind(px, py)),
+        z,
+        triangles,
+      ),
+    },
+  };
+}
+
+/** One bone of the rig as `encodeWeightedVertices` wants it. */
+function meshBoneRef(name: string, where: string, ctx: AttachmentContext): MeshBoneRef {
+  const transform = ctx.transforms.get(name);
+  if (!transform) throw new CompileError(`${where}: bone "${name}" has no setup transform`);
+  const index = ctx.bones.findIndex((b) => b.name === name);
+  if (index < 0) throw new CompileError(`${where}: bone "${name}" is not in the rig's bone list`);
+  return { index, toBind: (wx, wy) => toBoneLocal(transform, wx, wy) };
+}
+
+/**
+ * Read a one-channel sheet in a part's own pixel grid.
+ *
+ * Two callers want the same three refusals — the depth map and the soft-region
+ * mask — and both are a greyscale image that has to line up with the art. What
+ * they do with the levels differs; that a colour file or a mismatched size is a
+ * refusal by name does not.
+ *
+ * `purpose` only spells the messages. It is not a mode: the checks are the same
+ * either way, and a reader has to be told which of their inputs is at fault.
+ */
+function readGreySheet(
+  image: string,
+  purpose: 'depth' | 'soft',
+  partWidth: number,
+  partHeight: number,
+  where: string,
+  ctx: AttachmentContext,
+): { map: DepthMap; cover: Uint8Array; opaqueEverywhere: boolean } {
+  const noun = purpose === 'depth' ? 'depth map' : 'soft mask';
+  if (typeof image !== 'string' || image.length === 0) {
+    throw new CompileError(`${where}: the "${purpose}" block has no image to read`);
+  }
+  const path = join(ctx.imagesDir, image);
+  if (!existsSync(path)) {
+    throw new CompileError(`${where}: the ${noun} "${image}" is not at ${relative(process.cwd(), path)}`);
+  }
+  const sheet = readPlate(path);
+  if (sheet.width !== partWidth || sheet.height !== partHeight) {
+    throw new CompileError(
+      `${where}: the ${noun} "${image}" is ${sheet.width}x${sheet.height} and the part is ` +
+        `${partWidth}x${partHeight}. It is sampled in the part's own pixel grid, so the two are the same size — ` +
+        'resample the sheet, or point at the one that was made for this part.',
+    );
+  }
+  // One channel, proved rather than assumed.
+  const level = new Uint8Array(partWidth * partHeight);
+  const cover = new Uint8Array(partWidth * partHeight);
+  let opaqueEverywhere = true;
+  for (let i = 0; i < level.length; i++) {
+    const r = sheet.data[i * 4];
+    const g = sheet.data[i * 4 + 1];
+    const b = sheet.data[i * 4 + 2];
+    if (r !== g || g !== b) {
+      throw new CompileError(
+        `${where}: the ${noun} "${image}" is not greyscale — pixel (${i % partWidth}, ${Math.floor(i / partWidth)}) ` +
+          `is rgb(${r}, ${g}, ${b}). It is one channel; reading red out of a colour file would use whatever that ` +
+          'channel happened to hold.',
+      );
+    }
+    level[i] = r;
+    const a = sheet.data[i * 4 + 3];
+    cover[i] = a;
+    if (a !== 255) opaqueEverywhere = false;
+  }
+  return { map: { width: partWidth, height: partHeight, level }, cover, opaqueEverywhere };
+}
+
+/**
+ * Read a soft-region mask and turn it into mesh weights on a second bone.
+ *
+ * ⭐ The level IS the weight — black still, white carried — sampled at each
+ * vertex with the same bilinear the depth map uses, so a painted falloff
+ * reaches the mesh as a painted falloff. The remainder always stays on the slot
+ * bone, so every vertex closes at 1 by construction rather than by A20 catching
+ * it later.
+ *
+ * 🚨 This was a DEPTH THRESHOLD for one day and that was wrong: softness and
+ * prominence are different properties, the most prominent thing on a face is
+ * the nose, and a nose does not wobble. See `RigSoftRegion` for the whole of
+ * that correction.
+ */
+function softRegionWeights(
+  spec: RigSoftRegion,
+  points: ReadonlyArray<readonly [number, number]>,
+  partWidth: number,
+  partHeight: number,
+  where: string,
+  ctx: AttachmentContext,
+): { weights: MeshVertexWeight[][]; bone: string; mask: string; digest: string; carried: number; ramped: number } {
+  const { bone } = spec;
+  if (typeof bone !== 'string' || bone.length === 0) {
+    throw new CompileError(`${where}: the "soft" block has no "bone"; it is the bone the soft region is carried by`);
+  }
+  if (!ctx.bones.some((b) => b.name === bone)) {
+    throw new CompileError(
+      `${where}: "soft" names bone "${bone}", which this rig does not declare. rigc binds a region to a bone that ` +
+        'already exists rather than creating one — a bone a physics constraint has to target is part of the ' +
+        'skeleton, not a side effect of a mesh.',
+    );
+  }
+  if (bone === ctx.anchorBone) {
+    throw new CompileError(
+      `${where}: "soft" names "${bone}", which is this slot's own bone. Carrying the region with the bone the rest ` +
+        'of the mesh is already pinned to moves nothing — a soft region needs a bone that can move independently, ' +
+        'which is what a physics constraint is put on.',
+    );
+  }
+  const { map: sheet } = readGreySheet(spec.mask, 'soft', partWidth, partHeight, where, ctx);
+  let carried = 0;
+  let ramped = 0;
+  const weights = points.map(([x, y]) => {
+    const w = sampleLevel(sheet, x, y) / 255;
+    if (w >= 1) carried++;
+    else if (w > 0) ramped++;
+    if (w <= 0) return [{ bone: 'anchor', weight: 1 }] as MeshVertexWeight[];
+    if (w >= 1) return [{ bone: 'control', control: 0, weight: 1 }] as MeshVertexWeight[];
+    return [
+      { bone: 'anchor', weight: 1 - w },
+      { bone: 'control', control: 0, weight: w },
+    ] as MeshVertexWeight[];
+  });
+  if (carried === 0 && ramped === 0) {
+    throw new CompileError(
+      `${where}: the soft mask "${spec.mask}" carries no vertex of this mesh — every one of its ${points.length} ` +
+        'vertices samples black. A region that moves nothing is a physics constraint with nothing on the end of it; ' +
+        'check that the mask is painted where the mesh actually is, and that it is white where the art is soft.',
+    );
+  }
+  return { weights, bone, mask: spec.mask, digest: depthDigest(sheet), carried, ramped };
+}
+
+/**
+ * Build a `grid` mesh: a lattice over the part window, at stated positions.
+ *
+ * It shares `contour`'s placement and weighting exactly — the window is the
+ * PNG's own size, the mesh is centred on its slot bone, and every vertex is
+ * pinned to that bone at weight 1 — and differs only in where the vertices go.
+ * The two are kept as separate functions rather than one with a branch because
+ * what they measure is different: a contour asks the art where its edge is and
+ * reports how well it covered it, and a grid asks nothing of the art at all.
+ *
+ * ⭐ Why this exists at all: the lattice was being written BY HAND. The worked
+ * portrait shipped 25 vertex pairs, 32 triangles and a perimeter numbered in
+ * the one order the loader accepts — all of it a person's arithmetic, on the
+ * one topology whose correctness is least visible. A hand-numbered hull that
+ * lists an interior vertex first loads, draws and deforms wrong.
+ */
+function buildGridAttachment(
+  att: RigMeshAttachment,
+  generator: Extract<NonNullable<RigMeshAttachment['generator']>, { kind: 'grid' }>,
+  placeholder: string,
+  where: string,
+  ctx: AttachmentContext,
+): SpineMeshAttachment {
+  if (att.image === undefined) {
+    throw new CompileError(
+      `${where}: a "grid" generator lays its lattice over the part's own window, so the attachment needs an ` +
+        '"image" — there is nothing else here that says how big that window is',
+    );
+  }
+  const stated = generator.us !== undefined || generator.vs !== undefined;
+  const even = generator.cols !== undefined || generator.rows !== undefined;
+  if (stated && even) {
+    throw new CompileError(
+      `${where}: the "grid" generator states both positions ("us"/"vs") and a count ("cols"/"rows"). They are two ` +
+        'answers to where the columns go, and a spec carrying both leaves a reader unable to say which one built ' +
+        'the mesh. Drop one — positions are the more precise of the two.',
+    );
+  }
+  if (!stated && !even) {
+    throw new CompileError(
+      `${where}: the "grid" generator says neither where its columns go ("us"/"vs", fractions of the window) nor ` +
+        'how many there are ("cols"/"rows"). A lattice is not a default.',
+    );
+  }
+  const spread = (n: unknown, name: string): number[] => {
+    if (typeof n !== 'number' || !Number.isInteger(n) || n < 2) {
+      throw new CompileError(`${where}: "${name}" is ${JSON.stringify(n)}; it is a whole number of at least 2`);
+    }
+    // An even division spans the whole window. A lattice that should sit inside
+    // it states its own positions — which is what `us`/`vs` are for.
+    return Array.from({ length: n }, (_, i) => i / (n - 1));
+  };
+  const us = stated ? generator.us : spread(generator.cols, 'cols');
+  const vs = stated ? generator.vs : spread(generator.rows, 'rows');
+  if (us === undefined || vs === undefined) {
+    throw new CompileError(
+      `${where}: the "grid" generator states ${us === undefined ? '"vs"' : '"us"'} and not ` +
+        `${us === undefined ? '"us"' : '"vs"'}; a lattice needs both axes`,
+    );
+  }
+
+  const region = basename(att.image, '.png');
+  const img = ctx.images.find((im) => im.region === region);
+  if (!img) throw new CompileError(`${where}: no compiled image for "${att.image}"`);
+  const plate = partPlate(img);
+
+  let geometry;
+  try {
+    geometry = buildGridMesh({ size: [plate.width, plate.height], us, vs });
+  } catch (err) {
+    if (err instanceof MeshError) throw new CompileError(`${where}: ${err.message}`);
+    throw err;
+  }
+
+  const w = img.width;
+  const h = img.height;
+  const toArt = w / plate.width;
+  if (att.width !== undefined && att.width !== w) {
+    throw new CompileError(`${where}: the spec says width ${att.width} and "${att.image}" measures ${w}`);
+  }
+  if (att.height !== undefined && att.height !== h) {
+    throw new CompileError(`${where}: the spec says height ${att.height} and "${att.image}" measures ${h}`);
+  }
+  const anchor = ctx.transforms.get(ctx.anchorBone);
+  if (!anchor) throw new CompileError(`${where}: slot bone "${ctx.anchorBone}" has no setup transform`);
+  const index = ctx.bones.findIndex((b) => b.name === ctx.anchorBone);
+  if (index < 0) throw new CompileError(`${where}: slot bone "${ctx.anchorBone}" is not in the rig's bone list`);
+  // Sampled BEFORE the encode, because `bind` rewrites the weights the encode
+  // then writes out.
+  const depth =
+    generator.depth === undefined
+      ? undefined
+      :
+        sampleMeshDepth(
+          generator.depth,
+          'grid',
+          geometry.points,
+          geometry.triangles,
+          (px, py) => toBoneLocal(anchor, anchor.worldX + px * toArt - w / 2, anchor.worldY + h / 2 - py * toArt),
+          plate.width,
+          plate.height,
+          where,
+          ctx,
+        );
+  const bound =
+    generator.soft === undefined
+      ? undefined
+      : softRegionWeights(generator.soft, geometry.points, plate.width, plate.height, where, ctx);
+  if (bound) geometry = { ...geometry, weights: bound.weights };
+  const vertices = encodeWeightedVertices(
+    geometry,
+    (px, py) => [r6(anchor.worldX + px * toArt - w / 2), r6(anchor.worldY + h / 2 - py * toArt)],
+    {
+      anchor: { index, toBind: (wx, wy) => toBoneLocal(anchor, wx, wy) },
+      controls: bound ? [meshBoneRef(bound.bone, where, ctx)] : [],
+    },
+  );
+  ctx.meshBones.add(ctx.anchorBone);
+  if (bound) ctx.meshBones.add(bound.bone);
+  if (depth !== undefined) ctx.depths.set(`${ctx.skinName}/${ctx.slotName}/${placeholder}`, depth.z);
+  ctx.meshes.push({
+    slot: ctx.slotName,
+    kind: 'grid',
+    attachments: [placeholder],
+    vertices: geometry.uvs.length / 2,
+    triangles: geometry.triangles.length / 3,
+    bones: bound ? [ctx.anchorBone, bound.bone] : [ctx.anchorBone],
+    depth: depth?.summary,
+    soft:
+      bound === undefined
+        ? undefined
+        : { mask: bound.mask, digest: bound.digest, bone: bound.bone, carried: bound.carried, ramped: bound.ramped },
+  });
+  const out: SpineMeshAttachment = {
+    type: 'mesh',
+    uvs: geometry.uvs,
+    triangles: geometry.triangles,
+    vertices,
+    ...generatedHullAndEdges(geometry, where),
+    width: r6(w),
+    height: r6(h),
+  };
+  if (att.path !== undefined) out.path = att.path;
+  else if (region !== placeholder) out.path = region;
+  if (att.color !== undefined) out.color = att.color;
+  return out;
+}
+
 /** Defaults for the `contour` generator's optional parameters, stated once. */
 const CONTOUR_DEFAULTS = { margin: 1, maxVertices: 64, alpha: 1 } as const;
 
@@ -2731,6 +3206,25 @@ function buildContourAttachment(
     { anchor: { index, toBind: (wx, wy) => toBoneLocal(anchor, wx, wy) }, controls: [] },
   );
   ctx.meshBones.add(ctx.anchorBone);
+  // The depth map is sampled on the TRACED grid — the plate's — because that is
+  // the grid the vertices are in. `toArt` scales positions into world units
+  // afterwards and does not touch `z`, which carries its own stated scale.
+  const depth =
+    generator.depth === undefined
+      ? undefined
+      :
+        sampleMeshDepth(
+          generator.depth,
+          'contour',
+          geometry.points,
+          geometry.triangles,
+          (px, py) => toBoneLocal(anchor, anchor.worldX + px * toArt - w / 2, anchor.worldY + h / 2 - py * toArt),
+          plate.width,
+          plate.height,
+          where,
+          ctx,
+        );
+  if (depth !== undefined) ctx.depths.set(`${ctx.skinName}/${ctx.slotName}/${placeholder}`, depth.z);
   ctx.meshes.push({
     slot: ctx.slotName,
     kind: 'contour',
@@ -2741,6 +3235,7 @@ function buildContourAttachment(
     coverage: geometry.contour?.coverage,
     overshoot: geometry.contour?.overshoot,
     holePixels: geometry.contour?.holePixels,
+    depth: depth?.summary,
   });
   const out: SpineMeshAttachment = {
     type: 'mesh',
@@ -2778,6 +3273,12 @@ interface ConstraintContext {
   pathSlots: Map<string, string[]>;
   /** Animations the motion spec declares — a slider names one of them. */
   animationNames: Set<string>;
+  /**
+   * The duration each of those declares, which is what turns a slider's
+   * `from`/`to`/`scale` into the range of driving values that can reach a frame.
+   * Only the slider's 360° refusal reads it.
+   */
+  animationDurations: Map<string, number>;
 }
 
 /**
@@ -2960,6 +3461,57 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
         // time = to + (value - from) * 0, so the slider holds one frame forever.
         throw new CompileError(`${where}: scale is 0, so the bone's property cannot move the slider's time at all`);
       }
+      // ⚠️ `local: false` reads the bone's WORLD rotation, and `FromRotate.value`
+      // (`TransformConstraintData.js`) ends
+      //
+      //   let value = Math.atan2(source.c / sy, source.a / sx) * radDeg + …;
+      //   if (value < 0) value += 360;
+      //
+      // so a driving value below 0° is one the runtime never produces: it arrives
+      // as `value + 360` instead, and `time = to + (value - from) * scale` then
+      // lands far outside the animation. A yaw axis with its neutral at 0° — the
+      // natural way to author a face — therefore has its entire negative half
+      // pinned to one frame, and nothing anywhere says so (issue #402).
+      //
+      // ⭐ Refused here rather than documented, and rather than left to the gate,
+      // for three reasons. The failure is invisible AND total, so a note in a
+      // guide is read after the loss rather than before it. The fix is one field
+      // in the rig spec, which is the file this message can name — an artifact
+      // -side assertion would have to name the emitted `local`/`offset` fields the
+      // author never typed. And the arithmetic that proves it needs the
+      // animation's declared DURATION, which is a motion-spec fact the compiler
+      // has in front of it: the range of driving values that can reach a frame is
+      // exactly `[to, to + duration]` mapped back through `scale`.
+      //
+      // The refusal is deliberately narrow: `rotate` only, because `FromRotate` is
+      // the one property whose reader wraps, and only when the range actually
+      // crosses (or sits below) 0°, because a dial authored at 340°..20° is how
+      // you write this axis under `local: false` and it works.
+      if (property === 'rotate' && spec.local !== true) {
+        const fromValue = spec.from === undefined ? 0 : needNumber(spec.from, 'from');
+        const toTime = spec.to === undefined ? 0 : needNumber(spec.to, 'to');
+        const perUnit = spec.scale === undefined ? 1 : needNumber(spec.scale, 'scale');
+        const duration = ctx.animationDurations.get(animation) ?? 0;
+        /** The driving value that maps to the animation's first frame, and to its last. */
+        const atStart = fromValue - toTime / perUnit;
+        const atEnd = fromValue + (duration - toTime) / perUnit;
+        const lowest = Math.min(atStart, atEnd);
+        const highest = Math.max(atStart, atEnd);
+        if (lowest < -1e-6) {
+          const readAs = lowest + 360;
+          const lands = toTime + (readAs - fromValue) * perUnit;
+          throw new CompileError(
+            `${where}: drives off bone "${String(spec.bone)}" rotate with "local": false, and the driving values ` +
+              `that reach animation "${animation}" (0s..${duration}s) run from ${lowest.toFixed(3)}° to ${highest.toFixed(3)}°. ` +
+              'A world rotation is read through `FromRotate.value`, which ends `if (value < 0) value += 360`, so the bone ' +
+              `at ${lowest.toFixed(3)}° is read as ${readAs.toFixed(3)}° and maps to time ${lands.toFixed(3)}s — outside ` +
+              `the animation's ${duration}s. With "loop": false that is \`Math.max(0, time)\` holding the last frame; with ` +
+              '"loop": true it wraps to some other frame. Either way the whole part of the range below 0° is dead and ' +
+              'nothing at runtime reports it. Add `"local": true` to read the bone\'s own rotation signed and unwrapped — ' +
+              'that is the form a face axis wants — or move the range so it does not cross 0°.',
+          );
+        }
+      }
       for (const field of timeSide) {
         if (spec[field] !== undefined) {
           throw new CompileError(
@@ -3054,6 +3606,8 @@ function buildRigInfo(
   }
   const meshKinds: RigInfo['meshKinds'] = {};
   for (const mesh of meshes) meshKinds[mesh.slot] = mesh.kind;
+  const meshSoftBones: RigInfo['meshSoftBones'] = {};
+  for (const mesh of meshes) if (mesh.soft !== undefined) meshSoftBones[mesh.slot] = mesh.soft.bone;
   // A fold exemption on a slot that carries no mesh cannot exempt anything —
   // A39 reads triangles, and only a mesh has them. `parseRigSpec` already
   // refused a name that is not a SLOT; this is the second half, and it needs
@@ -3090,6 +3644,7 @@ function buildRigInfo(
     detached: (rig.invariants?.detached ?? []).map((d) => [d.bone, d.notUnder] as [string, string]),
     slotOrder: rig.slots.length ? rig.slots.map((s) => s.name) : null,
     meshKinds,
+    meshSoftBones,
     deformMayFold,
     meshSlotBudget: rig.invariants?.meshSlots ?? null,
     meshTriangleBudget: rig.invariants?.meshTriangles ?? null,
@@ -3744,19 +4299,51 @@ interface DeformGeometry {
   /** Bone influences per vertex, in vertex order. Null on an unweighted attachment. */
   boneCounts: number[] | null;
   /**
-   * Setup `x, y` per vertex **in the space a deform offset lives in**, for a
-   * `transform` key to evaluate a model over (issue #294).
+   * Setup `x, y` per vertex, for a `transform` key to evaluate a model over
+   * (issue #294).
+   *
+   * ⚠️ **Two spaces, and `influenceBones` is which.** Where every vertex of
+   * the attachment occupies exactly one pair of one bone's bind space — an
+   * unweighted run, or a weighted one whose every vertex is a single influence
+   * of a single bone — this is that space, the model's output IS the deform
+   * array, and `influenceBones` is null. Where it is not, this is the
+   * vertex's setup **world** position, `Σ wᵢ · Mᵢ · bindᵢ`, which is defined for
+   * any weighting; the model's output is then a world displacement that the
+   * caller pushes into each influence through `influenceBones`.
+   *
+   * That seam is deliberate and it is the reason the field is documented rather
+   * than named: keeping the first case in its own space is what makes the
+   * change to the second byte-for-byte invisible to every rig that already
+   * compiles (issue #389's own gate). It does mean a `radius` or an `about` is
+   * read in world units the moment a second bone touches any vertex, so the
+   * report says which space it evaluated in whenever it is not the first one.
    *
-   * Null when there is no single such space, and `setupWhy` then says which of
-   * the two reasons it was: a vertex with more than one bone on it, whose offset
-   * is a weighted sum of a pair in each bone's own bind space; or a run bound to
-   * several bones, where one closed form would be evaluated across several
-   * unrelated coordinate systems. Both are the `fromVertex` refusal's reasoning
-   * applied to a whole run — rigc will not guess a space.
+   * Null only in the one case that has no identity behind it: weights that do
+   * not close at 1. `setupWhy` then says so.
    */
   setup: number[] | null;
+  /**
+   * The setup world transform of the bone behind each influence, in the deform
+   * array's **own order** — one entry per pair — or null when `setup` is
+   * already the space the array is in.
+   *
+   * Non-null is the multi-influence path: a vertex's world displacement `D`
+   * becomes `Mᵢ⁻¹ · D` in every one of its influences (`toBoneLocalVector`), so
+   * the runtime's `Σ wᵢ · Mᵢ · Mᵢ⁻¹ · D` collapses to `D · Σ wᵢ = D` at setup,
+   * and to the same blend that carries the vertex once a bone moves.
+   */
+  influenceBones: BoneTransform[] | null;
   /** Why `setup` is null, phrased for the refusal. Null when it is not. */
   setupWhy: string | null;
+  /**
+   * Per-vertex `z`, when this attachment's generator named a depth map.
+   *
+   * Not measured from the emitted attachment like everything else here — there
+   * is nowhere in the format to measure it FROM, which is the whole reason the
+   * sampler keeps it beside the skeleton instead of in it. Filled in by the
+   * caller, which is where the skin, slot and attachment names live.
+   */
+  depth: readonly number[] | null;
 }
 
 /**
@@ -3766,7 +4353,14 @@ interface DeformGeometry {
  * all, so `attachment.vertices.length` throws inside the parser — one of the very
  * few places this format fails loudly, and it fails in the consumer's process.
  */
-function deformGeometryOf(att: SpineAttachment, where: string): DeformGeometry {
+function deformGeometryOf(
+  att: SpineAttachment,
+  where: string,
+  /** The emitted bone array, which a weight run's `boneIndex` indexes into. */
+  rigBones: SpineBone[],
+  /** Their setup world transforms, by name. */
+  transforms: Map<string, BoneTransform>,
+): DeformGeometry {
   const type = (att as { type?: string }).type ?? 'region';
   let worldVerticesLength: number;
   if (type === 'mesh') {
@@ -3800,7 +4394,11 @@ function deformGeometryOf(att: SpineAttachment, where: string): DeformGeometry {
       // An unweighted attachment IS its own space: the array is one `x, y` per
       // vertex in the slot bone's space, which is the space the offsets are in.
       setup: vertices.slice(),
+      influenceBones: null,
       setupWhy: null,
+      // Filled in by the caller; `deformGeometryOf` reads the emitted
+      // attachment, and the depth is deliberately not in it.
+      depth: null,
     };
   }
   // Walk the weight run for the per-vertex influence counts. The run's own shape
@@ -3809,6 +4407,8 @@ function deformGeometryOf(att: SpineAttachment, where: string): DeformGeometry {
   const boneCounts: number[] = [];
   const bindSpace: number[] = [];
   const bones = new Set<number>();
+  /** `boneIndex, bindX, bindY, weight` per influence, in deform-array order. */
+  const influenceRun: number[] = [];
   for (let i = 0; i < vertices.length; ) {
     const n = vertices[i++];
     if (!Number.isInteger(n) || n < 1) {
@@ -3818,10 +4418,12 @@ function deformGeometryOf(att: SpineAttachment, where: string): DeformGeometry {
       bones.add(vertices[i]);
       bindSpace.push(vertices[i + 1], vertices[i + 2]);
     }
+    const from = i;
     i += n * 4;
     if (i > vertices.length) {
       throw new CompileError(`${where}: the attachment's weighted vertex run is truncated at vertex ${boneCounts.length}`);
     }
+    for (let k = from; k < i; k++) influenceRun.push(vertices[k]);
     boneCounts.push(n);
   }
   // ⚠️ The influence count is the SUM of the per-vertex counts, not a division
@@ -3834,22 +4436,65 @@ function deformGeometryOf(att: SpineAttachment, where: string): DeformGeometry {
   // LOADED attachment, which is where the `/3*2` in the parser comes from.
   let influences = 0;
   for (const n of boneCounts) influences += n;
-  const multi = boneCounts.findIndex((n) => n !== 1);
-  const setupWhy =
-    multi !== -1
-      ? `vertex ${multi} has ${boneCounts[multi]} bone influences on it, and one x, y pair for such a vertex is not a ` +
-        'thing the deform array can hold: its world offset is the weighted sum of a pair in each bone\'s own bind space'
-      : bones.size > 1
-        ? `its ${boneCounts.length} vertices are bound to ${bones.size} different bones, so their x, y pairs are in ` +
-          'that many different bind spaces and one closed form evaluated across them would mean nothing'
-        : null;
+  const common = { weighted, deformLength: influences * 2, vertexCount: boneCounts.length, boneCounts, depth: null };
+  // -- one bind space, unchanged -------------------------------------------
+  //
+  // Every vertex a single influence of a single bone: the run IS that bone's
+  // bind space, a model evaluated over it lands straight in the deform array,
+  // and not one byte of this path moved for issue #389. Keeping it separate is
+  // what makes that provable — the alternative, folding it into the world path
+  // below, would re-evaluate every existing `transform` key at world
+  // coordinates and emit a different file for a spec nobody edited.
+  if (boneCounts.every((n) => n === 1) && bones.size === 1) {
+    return { ...common, setup: bindSpace, influenceBones: null, setupWhy: null };
+  }
+  // -- several influences, evaluated in world (issue #389) -------------------
+  //
+  // The refusal that used to stand here was right about the ARRAY and wrong
+  // about the MODEL. There is no single space the array lives in, true; but the
+  // vertex has one setup world position whatever its weighting —
+  // `Σ wᵢ · Mᵢ · bindᵢ` — and a world displacement `D` written into influence
+  // `i` as `Mᵢ⁻¹ · D` moves it by `D · Σ wᵢ`. So the model is evaluated once, in
+  // world, and pushed into each bind space rather than guessed at in one of
+  // them.
+  //
+  // ⭐ The one case with no identity behind it is a vertex whose weights do not
+  // close at 1, because that is the `Σ wᵢ` the arithmetic cancels against.
+  // `A20_MESH_WEIGHTS_COHERENT` is the assertion that requires it and 1e-3 is
+  // the tolerance it uses, quoted here rather than chosen again.
+  const setupWorld: number[] = [];
+  const influenceBones: BoneTransform[] = [];
+  let openWeights: string | null = null;
+  for (let v = 0, k = 0; v < boneCounts.length; v++) {
+    let wx = 0;
+    let wy = 0;
+    let sum = 0;
+    for (let n = 0; n < boneCounts[v]; n++, k++) {
+      const index = influenceRun[4 * k];
+      const bone = rigBones[index];
+      const m = bone === undefined ? undefined : transforms.get(bone.name);
+      if (!m) throw new CompileError(`${where}: vertex ${v} binds bone index ${index}, which is not in the bone list`);
+      const weight = influenceRun[4 * k + 3];
+      const [x, y] = toWorld(m, influenceRun[4 * k + 1], influenceRun[4 * k + 2]);
+      wx += x * weight;
+      wy += y * weight;
+      sum += weight;
+      influenceBones.push(m);
+    }
+    setupWorld.push(wx, wy);
+    if (openWeights === null && Math.abs(sum - 1) > 1e-3) {
+      openWeights =
+        `vertex ${v}'s ${boneCounts[v]} weights sum to ${sum.toFixed(4)} rather than 1. A stated model becomes a deform ` +
+        'run by writing each vertex\'s world displacement D into every influence as Mᵢ⁻¹·D, which moves the vertex by ' +
+        'D·Σwᵢ — so a sum that is not 1 has no displacement that lands it where the model says. ' +
+        'A20_MESH_WEIGHTS_COHERENT is the assertion that requires that sum, at the same 1e-3';
+    }
+  }
   return {
-    weighted,
-    deformLength: influences * 2,
-    vertexCount: boneCounts.length,
-    boneCounts,
-    setup: setupWhy === null ? bindSpace : null,
-    setupWhy,
+    ...common,
+    setup: openWeights === null ? setupWorld : null,
+    influenceBones: openWeights === null ? influenceBones : null,
+    setupWhy: openWeights,
   };
 }
 
@@ -3885,6 +4530,15 @@ function deformGeometryOf(att: SpineAttachment, where: string): DeformGeometry {
  * bone happens to share one world matrix. So that case is refused by name and
  * `offset` stays available for an author who really is writing bind-space
  * offsets per influence.
+ *
+ * ⭐ **A `transform` key is not in that bind, and since issue #389 it is not
+ * refused for it.** The difference is where the numbers come from: `fromVertex`
+ * hands rigc a pair the AUTHOR wrote, in a space only the author knows, and
+ * rigc will not guess which. A model states a displacement rigc evaluates
+ * itself, so it can put that displacement in world and push it into each
+ * influence through that bone's own inverse — `Σ wᵢ · Mᵢ · Mᵢ⁻¹ · D = D`, with
+ * nothing guessed. What survives is the one case the identity does not cover: a
+ * vertex whose weights do not close at 1.
  */
 function compileDeformTrack(
   track: MotionDeformTrack,
@@ -3916,9 +4570,9 @@ function compileDeformTrack(
     // `vertices` and would otherwise be read as the format's "back to the setup
     // pose". The three refusals are the bounds the issue drew: a key states one
     // or the other, never both; a model covers every vertex, so a start index
-    // has nothing to mean; and a model needs one coordinate space to be
-    // evaluated in, which a multi-bone or multi-space weighted attachment does
-    // not have.
+    // has nothing to mean; and a model has to land each vertex somewhere
+    // definite, which the arithmetic does for any weighting that closes at 1 and
+    // for no weighting that does not (issue #389).
     if (key.transform !== undefined) {
       if (key.vertices !== undefined && key.vertices !== null) {
         throw new CompileError(
@@ -3937,24 +4591,63 @@ function compileDeformTrack(
       }
       if (geometry.setup === null) {
         throw new CompileError(
-          `${where} (t=${key.t}): a "transform" is evaluated over the attachment's own setup geometry, and this ` +
-            `attachment has no single space to evaluate it in — ${geometry.setupWhy}. Key the control bone instead, or ` +
-            'write the bind-space pairs yourself and start the run with "offset".',
+          `${where} (t=${key.t}): a "transform" states where every vertex of this attachment goes, and this one has a ` +
+            `vertex the arithmetic cannot place — ${geometry.setupWhy}. Fix the weights, or write the bind-space pairs ` +
+            'yourself and start the run with "offset".',
+        );
+      }
+      const report = evaluateDeformTransform(key.transform, geometry.setup, r6, `${where} (t=${key.t})`, geometry.depth);
+      if (report.offsets.length !== geometry.vertexCount * 2) {
+        // Unreachable while `setup` is one pair per vertex, which is the whole
+        // reason both are derived from the same walk. Stated rather than
+        // assumed: a silent mismatch here is the overrun A35 exists for.
+        throw new CompileError(
+          `${where} (t=${key.t}): the transform produced ${report.offsets.length} numbers for ` +
+            `${geometry.vertexCount} vertices`,
         );
       }
-      const report = evaluateDeformTransform(key.transform, geometry.setup, r6, `${where} (t=${key.t})`);
-      if (report.offsets.length !== geometry.deformLength) {
-        // Unreachable while `setup` is one pair per vertex and `deformLength` is
-        // twice the vertex count, which is the whole reason both are derived
-        // from the same walk. Stated rather than assumed: a silent mismatch here
-        // is the overrun A35 exists for.
+      // -- one displacement per vertex -> one pair per influence (issue #389) -
+      //
+      // On a single-space attachment the two are the same array and this is a
+      // no-op by construction. On a multi-influence one the model's output is a
+      // WORLD displacement, and it reaches the deform array through each
+      // influencing bone's own inverse: `Σ wᵢ · Mᵢ · Mᵢ⁻¹ · D = D`. The
+      // displacement it expands is the ROUNDED one the report prints, so a
+      // reader can reproduce every emitted pair from the audit rather than from
+      // a second evaluation.
+      const run = expandDeformToInfluences(report.offsets, geometry);
+      if (run.length !== geometry.deformLength) {
         throw new CompileError(
-          `${where} (t=${key.t}): the transform produced ${report.offsets.length} numbers and this attachment's deform ` +
+          `${where} (t=${key.t}): the transform expanded to ${run.length} numbers and this attachment's deform ` +
             `array is ${geometry.deformLength} long`,
         );
       }
-      generated.push({ animation: animName, skin, slot: track.slot, attachment: track.attachment, time, ...report });
-      out.push({ time, vertices: report.offsets });
+      generated.push({
+        animation: animName,
+        skin,
+        slot: track.slot,
+        attachment: track.attachment,
+        time,
+        ...report,
+        // ⚠️ Which space the model was read in is not a detail: `radius`,
+        // `about`, `from` and `to` all mean something different in world
+        // coordinates, and a reader comparing two keys on two attachments has no
+        // other way to know they were not evaluated alike. Said only on the path
+        // where it is not the attachment's own space, so every existing report
+        // prints exactly the lines it printed before.
+        ...(geometry.influenceBones === null
+          ? {}
+          : {
+              expanded: run,
+              derived: [
+                ...report.derived,
+                `evaluated at setup WORLD positions, because ${geometry.vertexCount} vertices carry ` +
+                  `${geometry.deformLength / 2} influences; each displacement D is written into every influence as ` +
+                  'Mᵢ⁻¹·D, so the runtime composes Σwᵢ·Mᵢ·Mᵢ⁻¹·D = D',
+              ],
+            }),
+      });
+      out.push({ time, vertices: run });
       continue;
     }
     if (key.offset !== undefined && key.fromVertex !== undefined) {
@@ -4017,6 +4710,42 @@ function compileDeformTrack(
   return out;
 }
 
+/**
+ * A stated model's per-vertex displacement, as the deform array holds it.
+ *
+ * Two encodings once more, and the caller does not choose between them —
+ * `influenceBones` does, because it is null exactly when `setup` was already the
+ * array's own space:
+ *
+ *   one space  — the displacements ARE the array, returned untouched. This is
+ *                every `transform` key that compiled before issue #389, and
+ *                returning the same array object is what makes that visibly
+ *                true rather than arithmetically true.
+ *   several    — `D` is in world, and influence `i` of a vertex gets
+ *                `Mᵢ⁻¹ · D` (rotation and scale, no translation), which the
+ *                runtime sums back to `D · Σ wᵢ = D`.
+ *
+ * ⚠️ `toBoneLocalVector` and not `toBoneLocal`: a displacement has no origin to
+ * subtract, and subtracting one would move the vertex by the bone's own
+ * position. The coordinate contract lives in `src/transform.ts` and this reads
+ * it rather than restating it.
+ */
+function expandDeformToInfluences(displacements: number[], geometry: DeformGeometry): number[] {
+  const perInfluence = geometry.influenceBones;
+  if (perInfluence === null) return displacements;
+  const counts = geometry.boneCounts ?? [];
+  const out: number[] = [];
+  for (let v = 0, k = 0; v < counts.length; v++) {
+    const dx = displacements[2 * v];
+    const dy = displacements[2 * v + 1];
+    for (let n = 0; n < counts[v]; n++, k++) {
+      const [bx, by] = toBoneLocalVector(perInfluence[k], dx, dy);
+      out.push(r6(bx), r6(by));
+    }
+  }
+  return out;
+}
+
 /**
  * Where in the deform array this key's run begins.
  *