@rig-c/core 2.71.0 → 2.73.0

package/src/compile.ts

@@ -34,6 +34,8 @@ import {
   type DepthTone,
 } from './depth.ts';
 import { CompileError, NotImplementedError } from './errors.ts';
+import { alphaClipOutline, clipCarriers, refuseClipCrossing, refuseClipDegeneracy } from './alpha_clip.ts';
+import { regionCorners } from './core/vertices.ts';
 import { parseJsonWithPosition } from './json-position.ts';
 import { hypot2 } from './numeric.ts';
 // The "did you mean" list on a missing atlas region, from the one implementation
@@ -60,6 +62,7 @@ import {
   type RigBone,
   type RigBoundingBoxAttachment,
   type RigClippingAttachment,
+  type RigAlphaClip,
   type RigEvent,
   type RigLinkedMeshAttachment,
   type RigMeshAttachment,
@@ -2296,7 +2299,7 @@ function manifestShapeVisits(manifest: unknown): ShapeVisit[] {
  */
 export function compile(opts: CompileOptions): CompileResult {
   return withDroppedStates((droppedStates) => {
-    const { model, header, atlasText, declaredDurations } = compileInto(opts, droppedStates);
+    const { model, header, atlasText, declaredDurations, alphaClips } = compileInto(opts, droppedStates);
     // The skeleton: the Spine emitter's one entry (issue #922), which writes
     // every section from the model, in the order and under the spellings the
     // file has, and runs the parser-default and key-order passes on the
@@ -2314,6 +2317,7 @@ export function compile(opts: CompileOptions): CompileResult {
       atlasText,
       declaredDurations,
       ...carriedOf(model),
+      ...(alphaClips?.length ? { alphaClips } : {}),
       model,
     };
   });
@@ -2391,6 +2395,7 @@ export function headerBoundsOf(model: CompiledModel, atlasText: string): { box:
  * beside it to gate it, write its document and — if it asks — emit it.
  */
 export interface CompiledBuild {
+  alphaClips?: CompileResult['alphaClips'];
   /** The compiled model (`src/model.ts`), `stage` and `editorOrder` included (issue #1026). */
   model: CompiledModel;
   /** The rest of the Spine header the model does not hold (`SkeletonHeader`): what `compile` hands the emitter beside the model. */
@@ -3011,7 +3016,8 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   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[]>();
+  const attachmentDepths = new Map<string, number[] | { z: number[]; geometry: DeformGeometry }>();
+  const pendingAlphaClips: PendingAlphaClip[] = [];
   // The same for a `soft` mask's per-vertex level, which a deform envelope's
   // `mask` reads (issue #1413). Never emitted either.
   const attachmentSoftMasks = new Map<string, DeformSoftMask>();
@@ -3212,6 +3218,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
         const where = `skin "${skinName}" slot "${rigSlot.name}" attachment "${placeholder}"`;
         const built = buildRigAttachment(att, placeholder, where, {
           images,
+          pendingAlphaClips,
           bones,
           transforms,
           exactFrames,
@@ -3241,6 +3248,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   // line a linked mesh is the one construct in a rig spec whose name has not been
   // resolved yet.
   resolveLinkedMeshes(pendingLinks, skinTables);
+  const alphaClips = resolveAlphaClips(pendingAlphaClips, skinTables, rig, motion);
   // 📐 The implicit budget of 0 is a statement about rigc's own GENERATORS:
   // geometry rigc built is geometry rigc will not ship unmeasured, and
   // `A13_MESH_BUDGET` has nothing to measure a generated mesh against until the
@@ -3729,6 +3737,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
         if (deformTimelines.get(skinName)?.get(track.slot)?.has(track.attachment)) {
           throw new CompileError(`${at}: two deform timelines on one attachment; merge them into one`, 'CE_COMPILE_DEFORM_TIMELINE_DUPLICATE');
         }
+        const sampledDepth = attachmentDepths.get(`${skinName}/${track.slot}/${track.attachment}`);
         const keys = compileDeformTrack(
           track,
           motion,
@@ -3736,10 +3745,11 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
           anim.duration,
           {
             ...deformGeometryOf(attachment, at, transforms),
-            depth: attachmentDepths.get(`${skinName}/${track.slot}/${track.attachment}`) ?? null,
+            depth: (Array.isArray(sampledDepth) ? sampledDepth : sampledDepth?.z) ?? null,
             soft: attachmentSoftMasks.get(`${skinName}/${track.slot}/${track.attachment}`) ?? null,
           },
           deformTransforms,
+          sampledDepth !== undefined && !Array.isArray(sampledDepth) ? sampledDepth.geometry : null,
         );
         for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time);
         attachmentTimelinesOf(skinName, track.slot).set(track.attachment, { deform: keys });
@@ -3918,6 +3928,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
     header,
     atlasText,
     declaredDurations,
+    ...(alphaClips.length ? { alphaClips } : {}),
   };
 }
 
@@ -4340,6 +4351,7 @@ function refuseDefaultSkinContests(skinNames: readonly string[], skinParts: Map<
 // ---------------------------------------------------------------------------
 
 interface AttachmentContext {
+  pendingAlphaClips: PendingAlphaClip[];
   images: CompiledImage[];
   bones: ModelBone[];
   transforms: Map<string, BoneTransform>;
@@ -4367,7 +4379,7 @@ interface AttachmentContext {
    * 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[]>;
+  depths: Map<string, number[] | { z: number[]; geometry: DeformGeometry }>;
   /**
    * A `soft` mask's file and its sampled level per vertex, keyed like `depths`
    * — what a deform envelope's `mask` reads at key time (issue #1413). Never
@@ -4931,6 +4943,273 @@ function buildRigBoundingBox(
   return out;
 }
 
+interface PendingAlphaClip {
+  spec: RigAlphaClip;
+  out: ModelClippingAttachment;
+  where: string;
+  ctx: AttachmentContext;
+}
+
+/** Resolve after all sources/links exist: draw order cannot decide whether a source can be measured. */
+function resolveAlphaClips(
+  pending: PendingAlphaClip[],
+  tables: Map<string, SkinTable>,
+  rig: RigSpec,
+  motion: MotionSpec,
+): NonNullable<CompileResult['alphaClips']> {
+  const reports: NonNullable<CompileResult['alphaClips']> = [];
+  for (const { spec, out, where, ctx } of pending) {
+    const targetTable = tables.get(ctx.skinName)?.[ctx.slotName];
+    const target = Object.entries(targetTable ?? {}).find(([, value]) => value === out)?.[0];
+    // withStatedName can return a fresh object when name was declared.
+    const targetKey = target ?? Object.entries(targetTable ?? {}).find(([, value]) => value.kind === 'clipping' && value.vertices === out.vertices)?.[0];
+    if (targetKey === undefined) {
+      throw new CompileError(
+        `${where}: generated clipping target was not filed in its skin; required a resolved attachment.`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    for (const key of ['slot', 'skin', 'attachment'] as const) {
+      if (typeof spec[key] !== 'string' || spec[key].length === 0) {
+        throw new CompileError(
+          `${where}: alphaClip.${key} is ${JSON.stringify(spec[key])}; required an explicit nonempty source name.`,
+          'CE_COMPILE_ALPHA_CLIP_SOURCE',
+        );
+      }
+    }
+    const sourceWhere = `${spec.skin}/${spec.slot}/${spec.attachment}`;
+    const label = `${where} alphaClip from "${sourceWhere}"`;
+    const source = tables.get(spec.skin)?.[spec.slot]?.[spec.attachment];
+    const sourceSlot = rig.slots.find((slot) => slot.name === spec.slot);
+    if (!source || !sourceSlot) {
+      throw new CompileError(
+        `${label}: source attachment is absent; required a declared slot/skin/attachment.`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    if (source.kind !== 'region' && source.kind !== 'mesh' && source.kind !== 'linkedmesh') {
+      throw new CompileError(
+        `${label}: source kind is ${source.kind}; required a region or resolved mesh with pixels.`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    let geometry: SkinTableEntry = source;
+    let depthKey = sourceWhere;
+    if (geometry.kind === 'linkedmesh') {
+      depthKey = `${geometry.skin}/${geometry.slot}/${geometry.source}`;
+      const base = tables.get(geometry.skin)?.[geometry.slot]?.[geometry.source];
+      if (!base || base.kind !== 'mesh') {
+        throw new CompileError(
+          `${label}: linked source resolves to ${base?.kind ?? 'nothing'}; required a resolved mesh.`,
+          'CE_COMPILE_ALPHA_CLIP_SOURCE',
+        );
+      }
+      geometry = base;
+    }
+    if (geometry.kind !== 'region' && geometry.kind !== 'mesh') {
+      throw new CompileError(
+        `${label}: source is ${(geometry as SkinTableEntry).kind}; required region or mesh geometry with a plate (a clipping source would be a dependency cycle).`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    if (source.sequence !== undefined) {
+      throw new CompileError(
+        `${label}: source has a ${source.sequence.count}-frame sequence; required one immutable source plate. Select a separate named attachment for the measured frame.`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    const region = source.path ?? source.name ?? spec.attachment;
+    const img = ctx.images.find((image) => image.region === region);
+    if (!img) {
+      throw new CompileError(
+        `${label}: region "${region}" has no source plate; required image/atlas pixels.`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    if (img.pageGrid !== undefined) {
+      throw new CompileError(
+        `${label}: source plate grid cannot be located. ${img.pageGrid.sentence}`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    const plate = partPlate(img);
+    const mask = { width: plate.width, height: plate.height, alpha: plateAlpha(plate) };
+    const traced = alphaClipOutline(mask, spec, label, img.atlasScale ?? 1);
+    const ring = traced.points.map(([x, y]): [number, number] => [x / plate.width, y / plate.height]);
+    const anchor = ctx.transforms.get(sourceSlot.bone)!;
+    let sourceBindings: ModelBinding[][];
+    let uvs: number[];
+    let triangles: number[];
+    if (geometry.kind === 'region') {
+      // Full restored plate, not trimmed page rectangle: source crop pixels remain the coordinates.
+      const corners = regionCorners({ ...geometry, atlas: { width: img.width, height: img.height, originalWidth: img.width, originalHeight: img.height, offsetX: 0, offsetY: 0 } }, anchor);
+      uvs = [0, 1, 0, 0, 1, 0, 1, 1];
+      triangles = [0, 1, 2, 2, 3, 0];
+      sourceBindings = Array.from({ length: 4 }, (_, i) => {
+        const [x, y] = toBoneLocal(anchor, corners[2 * i], corners[2 * i + 1]);
+        return [{ bone: sourceSlot.bone, x, y, weight: 1 }];
+      });
+    } else {
+      uvs = geometry.uvs;
+      triangles = geometry.triangles;
+      const vertices = geometry.vertices;
+      sourceBindings = vertices.weighted ? vertices.bindings :
+        Array.from({ length: vertices.xy.length / 2 }, (_, i) => [{
+          bone: sourceSlot.bone, x: vertices.xy[2 * i], y: vertices.xy[2 * i + 1], weight: 1,
+        }]);
+    }
+    const carried = clipCarriers(ring, uvs, triangles, label);
+    if (carried.points.length > spec.maxVertices) {
+      throw new CompileError(
+        `${label}: polygonoverdeclaredvertexbudget: ${carried.points.length} vertices after source carrier crossings (${traced.points.length} simplified), required <=${spec.maxVertices}. Raise the declared budget or simplify the source/outline.`,
+        'CE_COMPILE_ALPHA_CLIP_VERTEX_BUDGET',
+      );
+    }
+    // Per-bone first moments preserve Σβ Σw M(bind) for every bone matrix; no solver or new pose model.
+    const bindings: ModelBinding[][] = carried.carriers.map((carrier) => {
+      const moments = new Map<string, { weight: number; x: number; y: number }>();
+      carrier.corners.forEach((index, corner) => {
+        for (const binding of sourceBindings[index]) {
+          const share = carrier.bary[corner] * binding.weight;
+          const row = moments.get(binding.bone) ?? { weight: 0, x: 0, y: 0 };
+          row.weight += share;
+          row.x += share * binding.x;
+          row.y += share * binding.y;
+          moments.set(binding.bone, row);
+        }
+      });
+      const result: ModelBinding[] = [];
+      for (const [bone, row] of moments) {
+        if (row.weight > 0) {
+          result.push({ bone, weight: f32(row.weight), x: f32(row.x / row.weight), y: f32(row.y / row.weight) });
+        }
+      }
+      return result;
+    });
+    out.vertices = { weighted: true, bindings };
+    out.vertexCount = bindings.length;
+    const mappedWorld = setupWorldVertices(out.vertices, anchor, ctx.transforms, label)
+      .map(([x, y]): [number, number] => [Math.fround(x), Math.fround(y)]);
+    refuseClipDegeneracy(mappedWorld, `${label} final float32 world coordinates`);
+    refuseClipCrossing(mappedWorld, label);
+    const sourceWorld = sourceBindings.map((vertex): [number, number] => {
+      let x = 0;
+      let y = 0;
+      for (const binding of vertex) {
+        const [wx, wy] = toWorld(ctx.transforms.get(binding.bone)!, binding.x, binding.y);
+        x += binding.weight * wx;
+        y += binding.weight * wy;
+      }
+      return [x, y];
+    });
+    let maxBindingDeviationWorld = 0;
+    carried.carriers.forEach((carrier, index) => {
+      let x = 0;
+      let y = 0;
+      carrier.corners.forEach((corner, k) => {
+        x += carrier.bary[k] * sourceWorld[corner][0];
+        y += carrier.bary[k] * sourceWorld[corner][1];
+      });
+      maxBindingDeviationWorld = Math.max(
+        maxBindingDeviationWorld,
+        hypot2(mappedWorld[index][0] - x, mappedWorld[index][1] - y),
+      );
+    });
+    const filed = targetTable![targetKey];
+    if (filed.kind === 'clipping') {
+      filed.vertices = out.vertices;
+      filed.vertexCount = out.vertexCount;
+    }
+    // Authored depth turns use setup-world geometry, even for a rigid source.
+    // Preserve that frame on the clip's own vertex/influence roster, not the source's.
+    const sourceDepth = ctx.depths.get(depthKey);
+    const z = sourceDepth === undefined || Array.isArray(sourceDepth) ? sourceDepth : sourceDepth.z;
+    let clipDepthGeometry: DeformGeometry | undefined;
+    if (z !== undefined) {
+      const depths = carried.carriers.map((carrier) =>
+        carrier.corners.reduce((sum, vertex, i) => sum + carrier.bary[i] * z[vertex], 0));
+      if (sourceDepth !== undefined && !Array.isArray(sourceDepth)) {
+        clipDepthGeometry = {
+          ...deformGeometryOf(out, label, ctx.transforms, ctx.transforms.get(ctx.anchorBone)!),
+          depth: depths,
+        };
+      }
+      ctx.depths.set(`${ctx.skinName}/${ctx.slotName}/${targetKey}`,
+        clipDepthGeometry === undefined ? depths : { z: depths, geometry: clipDepthGeometry });
+    }
+    // The helper, not the number of distinct bone names, defines the frame.
+    // Duplicate influences on one bone also take the world-space path.
+    const frameOf = (attachment: ModelVertexAttachment, unweightedBone: string, depthGeometry: DeformGeometry | undefined,
+      key: MotionDeformTrack['keys'][number] | undefined): {
+      name: string; geometry: DeformGeometry;
+    } => {
+      // Match compileDeformTrack's per-key choice, including authored depth:true.
+      const geometry = (key?.transform !== undefined && 'depth' in key.transform && key.transform.depth === true
+        ? depthGeometry : undefined) ?? deformGeometryOf(attachment, label, ctx.transforms);
+      const vertices = attachment.vertices;
+      const bone = vertices.weighted ? vertices.bindings[0]?.[0]?.bone : unweightedBone;
+      return { name: geometry.influenceBones === null ? `bone:${bone}` : 'world', geometry };
+    };
+    for (const [animationName, animation] of Object.entries(motion.animations ?? {})) {
+      const sourceIdentity = source.kind === 'linkedmesh' && source.timelines ? depthKey : sourceWhere;
+      const targetIdentity = `${ctx.skinName}/${ctx.slotName}/${targetKey}`;
+      const sourceTrack = animation.deform?.find((track) =>
+        `${track.skin ?? 'default'}/${track.slot}/${track.attachment}` === sourceIdentity);
+      const clipTrack = animation.deform?.find((track) =>
+        `${track.skin ?? 'default'}/${track.slot}/${track.attachment}` === targetIdentity);
+      if (!sourceTrack && !clipTrack) continue;
+      const sourceDepthGeometry = sourceDepth !== undefined && !Array.isArray(sourceDepth) ? sourceDepth.geometry : undefined;
+      const frames = (sourceTrack?.keys.length ? sourceTrack.keys : [undefined]).map((key, index) => ({
+        source: geometry.kind === 'mesh' ? frameOf(geometry, sourceSlot.bone, sourceDepthGeometry, key) : null,
+        clip: frameOf(out, ctx.anchorBone, clipDepthGeometry, clipTrack?.keys[index]),
+      }));
+      const compatible = frames.every(({ source, clip }) => source !== null && source.geometry.setup !== null &&
+        clip.geometry.setup !== null && source.name === clip.name);
+      const { source: sourceFrame, clip: clipFrame } = frames.find(({ source, clip }) =>
+        source === null || source.geometry.setup === null || clip.geometry.setup === null || source.name !== clip.name) ?? frames[0];
+      // With a world-space deform, varying per-vertex influence shares would
+      // correlate the deform with moving bone matrices. Constant shares commute
+      // with the affine/depth projection; no new deformation transfer is implied.
+      const sharesOf = (vertex: ModelBinding[]): string => {
+        const shares = new Map<string, number>();
+        for (const binding of vertex) {
+          shares.set(binding.bone, (shares.get(binding.bone) ?? 0) + binding.weight);
+        }
+        return JSON.stringify([...shares].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+      };
+      const constantWorldShares = !frames.some(({ source }) => source?.name === 'world') ||
+        sourceBindings.every((vertex) => sharesOf(vertex) === sharesOf(sourceBindings[0]));
+      const shared = sourceTrack !== undefined && clipTrack !== undefined &&
+        JSON.stringify(sourceTrack.keys) === JSON.stringify(clipTrack.keys);
+      const linear = sourceTrack?.keys.every((key) => {
+        const transform = key.transform;
+        return transform !== undefined && transform.envelope === undefined &&
+          (transform.kind === 'affine' || ((transform.kind === 'yaw' || transform.kind === 'pitch') &&
+            transform.depth === true && z !== undefined));
+      });
+      if (!shared || !linear || !compatible || !constantWorldShares) {
+        throw new CompileError(
+          `${label}: animation "${animationName}" has ${sourceTrack?.keys.length ?? 0} source and ` +
+            `${clipTrack?.keys.length ?? 0} clip keys; source frame=${sourceFrame?.name ?? 'no vertex geometry'}, ` +
+            `clip frame=${clipFrame.name}, constant world influence shares=${constantWorldShares}. ` +
+            'Required matching explicit affine/depth-yaw/pitch transforms in compatible DeformGeometry frames, ' +
+            'with constant shares for world-space transfer. Fix the named frame/keys or author corresponding clip motion.',
+          'CE_COMPILE_ALPHA_CLIP_DEFORM',
+        );
+      }
+    }
+    reports.push({
+      target: `${ctx.skinName}/${ctx.slotName}/${targetKey}`,
+      source: sourceWhere,
+      ...traced.report,
+      vertices: out.vertexCount,
+      uvs: carried.points,
+      maxBindingDeviationWorld,
+    });
+  }
+  return reports;
+}
+
 function buildRigClipping(
   att: RigClippingAttachment,
   where: string,
@@ -4954,9 +5233,15 @@ function buildRigClipping(
     ...(att.end !== undefined ? { end: att.end } : {}),
     ...(att.convex !== undefined ? { convex: att.convex } : {}),
     ...(att.inverse !== undefined ? { inverse: att.inverse } : {}),
-    vertexCount: att.vertexCount,
-    vertices: buildVertexGeometry(att, where, ctx),
+    vertexCount: att.vertexCount ?? 0,
+    vertices: att.alphaClip === undefined ? buildVertexGeometry({ ...att, vertexCount: att.vertexCount! }, where, ctx) : { weighted: false, xy: [] },
   };
+  if (att.alphaClip !== undefined) {
+    const fields = ['vertexCount', 'vertices', 'weights', 'boneIndexing'] as const;
+    const present = fields.filter((key) => att[key] !== undefined);
+    if (present.length || att.convex === true || att.inverse === true) throw new CompileError(`${where}: alphaClip conflicts with [${present.join(', ')}], convex=${att.convex}, inverse=${att.inverse}; required ordinary inside clipping with generated geometry only. Remove authored geometry/flags.`, 'CE_COMPILE_ALPHA_CLIP_CONFLICT');
+    ctx.pendingAlphaClips.push({ spec: att.alphaClip, out, where, ctx });
+  }
   if (att.color !== undefined) out.editorColor = att.color;
   return out;
 }
@@ -5755,7 +6040,12 @@ function buildRigMesh(
   if (authored && att.generator) {
     throw new CompileError(`${where}: a mesh is either authored geometry or a generator, never both`, 'CE_COMPILE_MESH_AUTHORED_AND_GENERATED');
   }
-  if (att.generator) return buildGeneratedMesh(att, att.generator, placeholder, where, ctx);
+  if (att.generator) {
+    if (att.depth !== undefined) {
+      throw new CompileError(`${where}: attachment "depth" describes authored geometry; a generated mesh states its depth on the contour or grid generator instead`, 'CE_COMPILE_DEPTH_AUTHORED_REQUIRED');
+    }
+    return buildGeneratedMesh(att, att.generator, placeholder, where, ctx);
+  }
   if (att.vertices && att.weights) {
     throw new CompileError(
       `${where}: a mesh gives geometry as "vertices" or as "weights", never both — "weights" is the by-name form of the same data`, 'CE_COMPILE_MESH_GEOMETRY_SOURCES_CONFLICT',
@@ -5833,6 +6123,35 @@ function buildRigMesh(
     height: f32(height),
   };
   if (att.sequence !== undefined) out.sequence = buildSequence(att.sequence);
+  let depth: ReturnType<typeof sampleMeshDepth> | undefined;
+  if (att.depth !== undefined) {
+    if (img === undefined) {
+      throw new CompileError(`${where}: an authored mesh with "depth" needs an "image" to locate the part's pixel grid`, 'CE_COMPILE_DEPTH_IMAGE_REQUIRED');
+    }
+    const anchor = ctx.transforms.get(ctx.anchorBone);
+    if (!anchor) throw new CompileError(`${where}: slot bone "${ctx.anchorBone}" has no setup transform`, 'CE_COMPILE_SLOT_SETUP_TRANSFORM_MISSING');
+    const geometry = deformGeometryOf(out, where, ctx.transforms, anchor);
+    if (geometry.setup === null) {
+      throw new CompileError(`${where}: depth needs resolved setup positions — ${geometry.setupWhy}`, 'CE_COMPILE_DEFORM_TRANSFORM_SETUP_UNRESOLVED');
+    }
+    const world = geometry.setup;
+    const plate = partPlate(img);
+    const toArt = img.width / plate.width;
+    // The generator's window is centred on the slot bone's setup WORLD origin.
+    // UVs describe texture placement, not a vertex's position in that window.
+    const points: Array<[number, number]> = [];
+    for (let v = 0; v < world.length; v += 2) {
+      points.push([(world[v] - anchor.worldX + img.width / 2) / toArt,
+        (img.height / 2 - (world[v + 1] - anchor.worldY)) / toArt]);
+    }
+    depth = sampleMeshDepth(att.depth, 'authored', points, att.triangles,
+      (px, py) => [anchor.worldX + px * toArt - img.width / 2, anchor.worldY + img.height / 2 - py * toArt],
+      img.pageGrid === undefined ? plateAlpha(plate) : { unlocated: img.pageGrid.said },
+      sheetGridOf(img, plate), where, ctx,
+      Array.from({ length: world.length / 2 }, (_, v) => [world[2 * v], world[2 * v + 1]]));
+    geometry.depth = depth.z;
+    ctx.depths.set(`${ctx.skinName}/${ctx.slotName}/${placeholder}`, { z: depth.z, geometry });
+  }
   // Register it as `authored`: geometry rigc did not build and whose topology it
   // therefore gets to assume nothing about. The generator-topology assertions
   // read this and skip rather than measuring a ring that was never a ring.
@@ -5843,6 +6162,7 @@ function buildRigMesh(
   ctx.meshes.push({
     slot: ctx.slotName,
     kind: 'authored',
+    ...(depth === undefined ? {} : { depth: depth.summary }),
     attachments: [ctx.slotName],
     vertices: uvCount / 2,
     triangles: att.triangles.length / 3,
@@ -6204,8 +6524,8 @@ function buildGeneratedMesh(
  * not invent tolerances.
  */
 function sampleMeshDepth(
-  spec: NonNullable<Extract<NonNullable<RigMeshAttachment['generator']>, { kind: 'contour' }>['depth']>,
-  kind: 'contour' | 'grid',
+  spec: RigDepthMap,
+  kind: 'contour' | 'grid' | 'authored',
   points: ReadonlyArray<readonly [number, number]>,
   /** The mesh's own triangle list, for the turn ceiling. */
   triangles: ReadonlyArray<number>,
@@ -6244,6 +6564,8 @@ function sampleMeshDepth(
   grid: SheetGrid,
   where: string,
   ctx: AttachmentContext,
+  /** Authored setup-world vertices, already in the depth turn's evaluation space. */
+  turnPoints?: ReadonlyArray<readonly [number, number]>,
 ): {
   z: number[];
   /** The tone-curved 0..1 nearness per vertex, which `bind` thresholds. */
@@ -6327,7 +6649,9 @@ function sampleMeshDepth(
       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 ' +
+        : kind === 'authored'
+          ? 'The authored setup vertices reach outside the sheet coverage. Extend the sheet to cover their bilinear taps, or correct the setup geometry.'
+          : '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(
@@ -6368,7 +6692,7 @@ function sampleMeshDepth(
       range: [f32(lo), f32(hi)],
       ...(partAlpha instanceof Uint8Array ? { undrawn } : { undrawn: null, unlocated: partAlpha.unlocated }),
       ceiling: turnCeiling(
-        points.map(([px, py]) => toBind(px, py)),
+        turnPoints ?? points.map(([px, py]) => toBind(px, py)),
         z,
         triangles,
         ctx.turnNarrowing === undefined ? undefined : { narrowing: ctx.turnNarrowing },
@@ -8737,7 +9061,7 @@ export interface DeformGeometry {
   /** 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.
+   * Per-vertex `z`, when this attachment or its generator named a depth map.
    *
    * Not measured from the attachment like everything else here — there
    * is nowhere in the format to measure it FROM, which is the whole reason the
@@ -8771,6 +9095,8 @@ export function deformGeometryOf(
   where: string,
   /** Every bone's setup world transform, by name. */
   transforms: Map<string, BoneTransform>,
+  /** Force the world-offset path for an authored depth turn, including rigid meshes. */
+  depthAnchor?: BoneTransform,
 ): DeformGeometry {
   const type = att.kind;
   let worldVerticesLength: number;
@@ -8816,6 +9142,15 @@ export function deformGeometryOf(
   const vertices = att.vertices;
   const weighted = vertices.weighted;
   if (!vertices.weighted) {
+    if (depthAnchor !== undefined) {
+      return {
+        weighted, deformLength: worldVerticesLength, vertexCount: worldVerticesLength / 2,
+        boneCounts: Array(worldVerticesLength / 2).fill(1),
+        setup: setupWorldVertices(vertices, depthAnchor, transforms, where).flat(),
+        influenceBones: Array(worldVerticesLength / 2).fill(depthAnchor),
+        setupWhy: null, depth: null, soft: null,
+      };
+    }
     return {
       weighted,
       deformLength: worldVerticesLength,
@@ -8879,7 +9214,7 @@ export function deformGeometryOf(
   // the runtime's last bits (`b = −2.3e-8` on an unrotated bone) into its
   // offset, about 1e-6 on gallery/look's hair locks. Evaluating on the authored
   // positions instead would need them carried here from the binder.
-  if (boneCounts.every((n) => n === 1) && bones.size === 1) {
+  if (depthAnchor === undefined && boneCounts.every((n) => n === 1) && bones.size === 1) {
     return { ...common, setup: bindSpace, influenceBones: null, setupWhy: null };
   }
   // -- several influences, evaluated in world (issue #389) -------------------
@@ -9055,6 +9390,7 @@ function compileDeformTrack(
   duration: number,
   geometry: DeformGeometry,
   generated: CompileResult['deformTransforms'],
+  depthWorld: DeformGeometry | null = null,
 ): ModelKey[] {
   const skin = track.skin ?? 'default';
   const where = `animation "${animName}" deform ${skin}/${track.slot}/${track.attachment}`;
@@ -9080,6 +9416,7 @@ function compileDeformTrack(
     // 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) {
+      const evaluated = ('depth' in key.transform && key.transform.depth === true ? depthWorld : null) ?? geometry;
       if (key.vertices !== undefined && key.vertices !== null) {
         throw new CompileError(
           `${where} (t=${key.t}): the key carries both a "transform" and a "vertices" run, and they are two answers to ` +
@@ -9090,33 +9427,33 @@ function compileDeformTrack(
       if (key.offset !== undefined || key.fromVertex !== undefined) {
         throw new CompileError(
           `${where} (t=${key.t}): the key states a "transform" and a start index. A transform is a model of the whole ` +
-            `attachment and is evaluated over all ${geometry.vertexCount} of its vertices, so it always starts at deform ` +
+            `attachment and is evaluated over all ${evaluated.vertexCount} of its vertices, so it always starts at deform ` +
             'index 0. A model applied to part of a run leaves a step at the run\'s edge — write the partial run by hand ' +
             'if that is what you mean.', 'CE_COMPILE_DEFORM_TRANSFORM_START_INDEX',
         );
       }
-      if (geometry.setup === null) {
+      if (evaluated.setup === null) {
         throw new CompileError(
           `${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 ` +
+            `vertex the arithmetic cannot place — ${evaluated.setupWhy}. Fix the weights, or write the bind-space pairs ` +
             'yourself and start the run with "offset".', 'CE_COMPILE_DEFORM_TRANSFORM_SETUP_UNRESOLVED',
         );
       }
       const report = evaluateDeformTransform(
         key.transform,
-        geometry.setup,
+        evaluated.setup,
         onModelGrid,
         `${where} (t=${key.t})`,
-        geometry.depth,
-        geometry.soft,
+        evaluated.depth,
+        evaluated.soft,
       );
-      if (report.offsets.length !== geometry.vertexCount * 2) {
+      if (report.offsets.length !== evaluated.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`, 'CE_COMPILE_DEFORM_TRANSFORM_OFFSET_COUNT',
+            `${evaluated.vertexCount} vertices`, 'CE_COMPILE_DEFORM_TRANSFORM_OFFSET_COUNT',
         );
       }
       // -- one displacement per vertex -> one pair per influence (issue #389) -
@@ -9128,11 +9465,11 @@ function compileDeformTrack(
       // 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) {
+      const run = expandDeformToInfluences(report.offsets, evaluated);
+      if (run.length !== evaluated.deformLength) {
         throw new CompileError(
           `${where} (t=${key.t}): the transform expanded to ${run.length} numbers and this attachment's deform ` +
-            `array is ${geometry.deformLength} long`, 'CE_COMPILE_DEFORM_TRANSFORM_RUN_LENGTH',
+            `array is ${evaluated.deformLength} long`, 'CE_COMPILE_DEFORM_TRANSFORM_RUN_LENGTH',
         );
       }
       generated.push({
@@ -9148,14 +9485,14 @@ function compileDeformTrack(
         // 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
+        ...(evaluated.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 ` +
+                `evaluated at setup WORLD positions, because ${evaluated.vertexCount} vertices carry ` +
+                  `${evaluated.deformLength / 2} influences; each displacement D is written into every influence as ` +
                   'Mᵢ⁻¹·D, so the runtime composes Σwᵢ·Mᵢ·Mᵢ⁻¹·D = D',
               ],
             }),

package/src/core/clipping.ts

@@ -633,7 +633,11 @@ export function clipThrough(
   clip: TriangleClipper = clipTriangles,
   reading: { dropRegion?: number } = {},
 ): ClipResult | null {
-  const plan = clipShapeOf(shape);
+  let plan = clipShapeOf(shape);
+  // CO11/CL01/CN06 and portal's convex rows need the original world doubles.
+  // Two 66-point region/authored up_minus15 pieces witnesses went from 2 to 0
+  // rendered pixel differences with Float32 input; SDK clipper storage was not observed.
+  if (plan.kind === 'pieces') plan = clipShapeOf({ ...shape, polygon: shape.polygon.map(Math.fround) });
   if (plan.kind === 'refused') return null;
   if (plan.kind === 'convex') return clip(plan.polygon, vertices, triangles, uvs);
   const f = Math.fround;