@rig-c/core 2.70.0 → 2.72.0

package/src/depth.ts

@@ -211,8 +211,8 @@ export function depthDigest(map: DepthMap): string {
  * be a different model. `u` is the point's offset from the axis; `z` is how far
  * in front of that axis it sits.
  */
-export function turnDisplacement(u: number, z: number, radians: number): number {
-  return u * (Math.cos(radians) - 1) - z * Math.sin(radians);
+export function turnDisplacement(u: number, z: number, radians: number, narrowing = true): number {
+  return (narrowing ? u * (Math.cos(radians) - 1) : 0) - z * Math.sin(radians);
 }
 
 /** What a field comparison measured. Pixels, in the part's own grid. */
@@ -676,10 +676,16 @@ export function turnCeiling(
   points: ReadonlyArray<readonly [number, number]>,
   z: readonly number[],
   triangles: ReadonlyArray<number>,
+  options?: { narrowing?: boolean | { yaw?: boolean; pitch?: boolean } },
 ): TurnCeiling {
   if (z.length !== points.length) {
     throw new DepthError(`the mesh has ${points.length} vertices and ${z.length} depths were supplied for it`);
   }
+  const narrowingOpt = options?.narrowing;
+  const narrowingByAxis = {
+    yaw: typeof narrowingOpt === 'object' ? narrowingOpt.yaw !== false : narrowingOpt !== false,
+    pitch: typeof narrowingOpt === 'object' ? narrowingOpt.pitch !== false : narrowingOpt !== false,
+  };
   const out: TurnCeiling = {
     yaw: { positive: null, negative: null },
     pitch: { positive: null, negative: null },
@@ -745,10 +751,17 @@ export function turnCeiling(
       ['pitch', dxb * dzc - dxc * dzb],
     ] as const) {
       // A zero here is a triangle the axis cannot fold at all: its area stays
-      // `A₀·cos t`, which only reaches zero at a right angle.
+      // `A₀·cos t` (or `A₀` when `narrowing` is false), which only reaches zero
+      // at a right angle or never.
       if (aAxis === 0) continue;
       const ratio = a0 / aAxis;
-      const degrees = (Math.atan(Math.abs(ratio)) * 180) / Math.PI;
+      const narrowing = narrowingByAxis[axis];
+      // With `narrowing: false`, `2A(t) = 2A₀ − 2A_axis·sin t`, which crosses
+      // zero at `sin t = A₀ / A_axis = ratio`. A ratio with `|ratio| >= 1` never
+      // crosses zero short of 90° (`|sin t| < 1` on `(0, 90°)`), so it is
+      // skipped for the same reason `aAxis === 0` is.
+      if (!narrowing && Math.abs(ratio) >= 1) continue;
+      const degrees = ((narrowing ? Math.atan(Math.abs(ratio)) : Math.asin(Math.abs(ratio))) * 180) / Math.PI;
       const side = ratio > 0 ? 'positive' : 'negative';
       angles[axis][side].push(degrees);
       const held = out[axis][side];

package/src/meshcompare.ts

@@ -107,6 +107,7 @@ import {
   type SourceMesh,
   type WorstSample,
 } from './meshquality.ts';
+import { createHash } from 'node:crypto';
 import { areaBand, stretchSingularValues, triangleAreas } from './areaband.ts';
 import { uvCarriers, uvCarriersWith, type Carrier, type CarrierPlant } from './meshcarriers.ts';
 import { CoreInputError, readModel, underNoSkin, underSkin, type CompiledDocument } from './core/index.ts';
@@ -187,6 +188,12 @@ export interface MotionComparisonInput {
   overBound?: OverBoundRequest;
 }
 
+/** The candidate list is supplied on each use; every other input is bound to the reference. */
+export type MotionReferenceInput = Omit<MotionComparisonInput, 'candidates'>;
+
+/** An opaque reference prepared by {@link prepareMotionReference}. Its data is held outside the returned object. */
+export interface PreparedMotionReference { readonly kind: 'prepared-motion-reference/1' }
+
 /**
  * Issue #1291's faults in carrying `motionAmplitude` into the setup measurement, for the `mesh-compare` suite's
  * negative controls: the amplitude not handed over; `null` handed over as the field left out; the field not validated
@@ -896,6 +903,110 @@ function foldingSlots(raw: unknown, who: string): Set<string> {
   return new Set(list as string[]);
 }
 
+type GeometryRead = { geometry: EvidenceSection | null; counts: MeshCounts | null };
+type MotionRead = { section: EvidenceSection & { schedule: ScheduleUsed }; perFrame: NonNullable<CandidateReport['perFrame']>; overBound: OverBoundReport | null } | null;
+interface PreparedMotionData {
+  frames: Planned[];
+  walks: Walk[];
+  folding: Set<string>;
+  scheduleUsed: ScheduleUsed;
+  samplesOf: Array<{ samples: Sample[]; art: number }>;
+  refCarriers: Array<Array<Carrier | null>>;
+  posedRef: Posed | { refused: string };
+}
+interface PreparedState {
+  reference: Build;
+  refs: AttachmentRef[];
+  order: number[];
+  refGeometry: GeometryRead;
+  motionData: PreparedMotionData | null;
+  referenceMotion: MotionRead;
+  digests: Record<string, string>;
+}
+
+const preparedReferences = new WeakMap<PreparedMotionReference, PreparedState>();
+
+/** One digest per bound field, so a mismatch names the field instead of accepting a stale pose or mask. */
+function boundDigests(input: MotionReferenceInput): Record<string, string> {
+  // JSON.stringify maps -0 to 0, drops undefined object fields, and maps non-finite numbers to null. A bound
+  // option's signed zero can survive validation and is echoed in a report, so these are not safe digest aliases.
+  const exact = (value: unknown, visiting = new Set<object>()): unknown => {
+    if (value === null) return ['null'];
+    if (typeof value === 'number') return ['number', Object.is(value, -0) ? '-0' : String(value)];
+    if (typeof value === 'string' || typeof value === 'boolean' || typeof value === 'undefined') return [typeof value, value ?? null];
+    if (typeof value !== 'object') return [typeof value, String(value)];
+    if (visiting.has(value)) throw new Error('cyclic bound input');
+    visiting.add(value);
+    const encoded = Array.isArray(value)
+      ? ['array', Array.from({ length: value.length }, (_, i) => Object.prototype.hasOwnProperty.call(value, i) ? exact(value[i], visiting) : ['hole'])]
+      : ['object', Object.keys(value).map((key) => [key, exact((value as Record<string, unknown>)[key], visiting)])];
+    visiting.delete(value);
+    return encoded;
+  };
+  const digest = (value: unknown): string => createHash('sha256').update(JSON.stringify(exact(value))).digest('hex');
+  return {
+    reference: digest(input.reference),
+    schedule: digest(input.schedule),
+    attachments: digest(input.attachments.map((a) => ({
+      attachment: a.attachment,
+      art: { threshold: a.art.threshold, frame: a.art.frame, mask: {
+        width: a.art.mask.width,
+        height: a.art.mask.height,
+        alpha: createHash('sha256').update(a.art.mask.alpha).digest('hex'),
+      } },
+      finalThreshold: a.finalThreshold,
+      minArtSamples: a.minArtSamples,
+      regions: a.regions,
+    }))),
+    referenceArtFit: digest(input.referenceArtFit),
+    candidateArtFit: digest(input.candidateArtFit),
+    bounds: digest(input.bounds),
+    motionRequired: digest(input.motionRequired),
+    perFrame: digest(input.perFrame),
+    motionAmplitude: digest({ present: Object.prototype.hasOwnProperty.call(input, 'motionAmplitude'), value: input.motionAmplitude }),
+    overBound: digest({ present: Object.prototype.hasOwnProperty.call(input, 'overBound'), value: input.overBound }),
+  };
+}
+
+/** Prepare the source once for sequential candidates on the same schedule and the same art. */
+export function prepareMotionReference(input: MotionReferenceInput): PreparedMotionReference {
+  if (!isObject(input)) missing('the prepared reference input', input, 'a MotionReferenceInput object');
+  const ref: unknown = input.reference;
+  let id = 'prepared-candidate';
+  while (isObject(ref) && id === ref.id) id += '-';
+  const model = isObject(ref) && typeof ref.model === 'string' ? ref.model : '';
+  validateInput({ ...input, candidates: [{ id, model }] }, null);
+  // No caller-owned array enters the cache: a later mutation is detected against this snapshot at use.
+  let snapshot: MotionReferenceInput;
+  try { snapshot = structuredClone(input); }
+  catch (e) { refuse('COMPARE_INPUT_MISSING', `the prepared reference input cannot be copied (${(e as Error).message}); required cloneable model, schedule, art and options`); }
+  let state: PreparedState | null = null;
+  const asComparison: MotionComparisonInput = { ...snapshot, candidates: [{ id, model: snapshot.reference.model }] };
+  compareMeshesInMotionWith(asComparison, null, undefined, (ready) => { state = ready; });
+  if (state === null) throw new Error('prepareMotionReference: reference preparation produced no state');
+  const ready: PreparedState = state;
+  try { ready.digests = boundDigests(snapshot); }
+  catch (e) { refuse('COMPARE_INPUT_MISSING', `the prepared reference input cannot be digested (${(e as Error).message}); required a complete mask and comparison options`); }
+  const handle: PreparedMotionReference = Object.freeze({ kind: 'prepared-motion-reference/1' });
+  preparedReferences.set(handle, ready);
+  return handle;
+}
+
+/** Compare a candidate against the prepared source; every bound input must still have the prepared bytes. */
+export function comparePreparedMotion(handle: PreparedMotionReference, input: MotionComparisonInput): MeshQualityReport {
+  const ready = preparedReferences.get(handle);
+  if (ready === undefined) refuse('COMPARE_PREPARED_HANDLE', 'the prepared reference handle was not made by prepareMotionReference; required its opaque handle');
+  let now: Record<string, string>;
+  try { now = boundDigests(input); }
+  catch { refuse('COMPARE_PREPARED_MISMATCH', 'the bound input cannot be digested; required the reference, schedule, attachments and options used to prepare the handle'); }
+  for (const [field, digest] of Object.entries(ready.digests)) {
+    if (now[field] !== digest) refuse('COMPARE_PREPARED_MISMATCH', `${field} changed after prepareMotionReference; required the same reference, schedule, art and options for this handle`);
+  }
+  const report = compareMeshesInMotionWith(input, null, ready);
+  if (report === null) throw new Error('comparePreparedMotion: comparison produced no report');
+  return report;
+}
+
 /**
  * Compare one or more candidate builds with a reference build in motion — §3
  * and §4's motion rows — and measure each build's art fit at the setup pose
@@ -907,7 +1018,9 @@ function foldingSlots(raw: unknown, who: string): Set<string> {
  * undercut at the setup pose fails `referenceArtFit`, and `measureMeshQuality`'s own codes for the art).
  */
 export function compareMeshesInMotion(input: MotionComparisonInput): MeshQualityReport {
-  return compareMeshesInMotionWith(input, null);
+  const report = compareMeshesInMotionWith(input, null);
+  if (report === null) throw new Error('compareMeshesInMotion: comparison produced no report');
+  return report;
 }
 
 /**
@@ -916,18 +1029,20 @@ export function compareMeshesInMotion(input: MotionComparisonInput): MeshQuality
  * surface*).
  */
 export function compareMeshesInMotionPlanted(input: MotionComparisonInput, plant: ComparePlant): MeshQualityReport {
-  return compareMeshesInMotionWith(input, plant);
+  const report = compareMeshesInMotionWith(input, plant);
+  if (report === null) throw new Error('compareMeshesInMotionPlanted: comparison produced no report');
+  return report;
 }
 
-function compareMeshesInMotionWith(input: MotionComparisonInput, plant: ComparePlant | null): MeshQualityReport {
+function compareMeshesInMotionWith(input: MotionComparisonInput, plant: ComparePlant | null, prepared?: PreparedState, capture?: (state: PreparedState) => void): MeshQualityReport | null {
   validateInput(input, plant);
   const amplitude = input.motionAmplitude;
   // What the setup measurement is handed: the field as the caller set it — left out as left out, `null` as `null`.
   const handed: { motionAmplitude?: MotionAmplitude | null } =
     plant === 'amplitude-not-carried' || amplitude === undefined || (plant === 'null-read-as-left-out' && amplitude === null) ? {} : { motionAmplitude: amplitude };
-  const refs = input.attachments.map((a) => a.attachment);
-  const reference = readBuild(input.reference, 'reference', refs);
-  const candidates = input.candidates.map((c, i) => readBuild(c, `candidates[${i}]`, refs));
+  const refs = prepared?.refs ?? input.attachments.map((a) => a.attachment);
+  const reference = prepared?.reference ?? readBuild(input.reference, 'reference', refs);
+  const candidates = capture === undefined ? input.candidates.map((c, i) => readBuild(c, `candidates[${i}]`, refs)) : [];
   for (const c of candidates) {
     const d = firstDifference(reference.raw, c.raw, [], refs);
     if (d !== null) {
@@ -939,13 +1054,13 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
   }
   // The slots in skeleton order fix the order attachments are reported in (§2).
   const slotRank = new Map(reference.doc.slots.map((s, i) => [s.name, i]));
-  const order = input.attachments.map((_a, i) => i).sort((p, q) => (slotRank.get(refs[p].slot) ?? 0) - (slotRank.get(refs[q].slot) ?? 0) || (refs[p].attachment < refs[q].attachment ? -1 : refs[p].attachment > refs[q].attachment ? 1 : 0));
+  const order = prepared?.order ?? input.attachments.map((_a, i) => i).sort((p, q) => (slotRank.get(refs[p].slot) ?? 0) - (slotRank.get(refs[q].slot) ?? 0) || (refs[p].attachment < refs[q].attachment ? -1 : refs[p].attachment > refs[q].attachment ? 1 : 0));
   for (const ref of refs) {
     if (!slotRank.has(ref.slot)) missing(`attachment ${nameOf(ref)}'s slot`, ref.slot, `one of the reference's slots [${[...slotRank.keys()].join(', ')}]`);
   }
 
   // --- the setup art fit, each build under its own bounds (§3 (a)) ----------------------------
-  const geometryOf = (b: Build, fit: ArtFitBounds): { geometry: EvidenceSection | null; counts: MeshCounts | null } => {
+  const geometryOf = (b: Build, fit: ArtFitBounds): GeometryRead => {
     const sections: EvidenceSection[] = [];
     const counts: MeshCounts[] = [];
     for (const i of order) {
@@ -987,7 +1102,7 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
     };
     return { geometry: joinSections(sections), counts: total };
   };
-  const refGeometry = geometryOf(reference, input.referenceArtFit);
+  const refGeometry = prepared?.refGeometry ?? geometryOf(reference, input.referenceArtFit);
   // §3 *Independent evidence* (a), P8: a reference that fails its own art fit — coverage, overshoot or undercut against
   // its own mask under `referenceArtFit` — is refused AS A REFERENCE: a deviation from a reference that does not carry
   // its own art is not evidence, so no candidate is measured against it. (a) is those three rows and no other: winding
@@ -1006,24 +1121,26 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
 
   // --- motion ---------------------------------------------------------------------------------
   const schedule = input.schedule;
-  type Motion = { section: EvidenceSection & { schedule: ScheduleUsed }; perFrame: NonNullable<CandidateReport['perFrame']>; overBound: OverBoundReport | null } | null;
   // Issue #1315: the request as the caller set it; `?? undefined` only matters under the unvalidated plant.
   const overBound: OverBoundRequest | undefined = input.overBound ?? undefined;
-  let motionOf: (b: Build, isReference: boolean) => Motion = () => null;
+  let motionOf: (b: Build, isReference: boolean) => MotionRead = () => null;
+  let motionData: PreparedMotionData | null = null;
   if (schedule !== null) {
-    const physicsConstraints = reference.doc.constraints.filter((c) => c.kind === 'physics').length;
-    const { frames, walks, walkSteps } = planSchedule(schedule, reference.doc, physicsConstraints);
-    const folding = foldingSlots(reference.raw, `reference "${reference.id}"`);
-    const scheduleUsed: ScheduleUsed = {
+    const existing = prepared?.motionData;
+    const planned = existing === undefined ? planSchedule(schedule, reference.doc, reference.doc.constraints.filter((c) => c.kind === 'physics').length) : null;
+    const frames = existing?.frames ?? planned!.frames;
+    const walks = existing?.walks ?? planned!.walks;
+    const folding = existing?.folding ?? foldingSlots(reference.raw, `reference "${reference.id}"`);
+    const scheduleUsed: ScheduleUsed = existing?.scheduleUsed ?? {
       ...schedule,
       walked: frames.map((f) => f.ref),
       roles: (['baseline', 'selection', 'held-out'] as const).filter((r) => frames.some((f) => f.ref.role === r)),
       heldOutClaim: frames.some((f) => f.ref.role === 'held-out'),
       reset: 'physics reset at time 0',
-      walks: walks.map((w, i) => ({ animation: w.animation, phase: w.phase, steps: walkSteps[i] })),
+      walks: walks.map((w, i) => ({ animation: w.animation, phase: w.phase, steps: planned!.walkSteps[i] })),
     };
     // The samples, per attachment: art pixel centres at the final threshold, then the reference hull's UVs (§3).
-    const samplesOf = order.map((i) => {
+    const samplesOf = existing?.samplesOf ?? order.map((i) => {
       const a = input.attachments[i];
       const { mask, frame } = a.art;
       const bits = artOf(mask, a.finalThreshold);
@@ -1046,9 +1163,10 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
     const carrierPlant: CarrierPlant | null = plant === 'slack-support-unread' || plant === 'narrowest-slack' || plant === 'any-shared-vertex' ? plant : null;
     const carriersOf = (uvs: readonly number[], triangles: readonly number[], samples: ReadonlyArray<{ uv: [number, number] }>, who: string): Array<Carrier | null> =>
       uvCarriersWith(uvs, triangles, samples, who, carrierPlant);
-    const refCarriers = order.map((i, k) => carriersOf(reference.meshes[i].uvs, reference.meshes[i].triangles, samplesOf[k].samples, `reference "${reference.id}", attachment ${nameOf(refs[i])}`));
+    const refCarriers = existing?.refCarriers ?? order.map((i, k) => carriersOf(reference.meshes[i].uvs, reference.meshes[i].triangles, samplesOf[k].samples, `reference "${reference.id}", attachment ${nameOf(refs[i])}`));
     const clock = plant === 'frame-physics-clock' ? 'frame' : 'render';
-    const posedRef = poseBuild(reference.doc, order.map((i) => refs[i]), frames, walks, clock);
+    const posedRef = existing?.posedRef ?? poseBuild(reference.doc, order.map((i) => refs[i]), frames, walks, clock);
+    motionData = { frames, walks, folding, scheduleUsed, samplesOf, refCarriers, posedRef };
 
     motionOf = (b: Build, isReference: boolean) => {
       const carriers = isReference ? refCarriers : order.map((i, k) => carriersOf(b.meshes[i].uvs, b.meshes[i].triangles, samplesOf[k].samples, `candidate "${b.id}", attachment ${nameOf(refs[i])}`));
@@ -1311,9 +1429,13 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
       return { section: { ...sectionOf(grouped), schedule: scheduleUsed }, perFrame, overBound: located };
     };
   }
-  const referenceMotion = motionOf(reference, true);
+  const referenceMotion = prepared?.referenceMotion ?? motionOf(reference, true);
+  if (capture !== undefined) {
+    capture({ reference, refs, order, refGeometry, motionData, referenceMotion, digests: {} });
+    return null;
+  }
   const candidateMotions = candidates.map((c) => motionOf(c, false));
-  const reportOf = (b: Build, geometry: { geometry: EvidenceSection | null; counts: MeshCounts | null }, measured: Motion, isCandidate: boolean): CandidateReport => {
+  const reportOf = (b: Build, geometry: GeometryRead, measured: MotionRead, isCandidate: boolean): CandidateReport => {
     const motion = measured === null ? null : measured.section;
     // P6: the geometry verdict pass (every required row measured and passing), and — when motion is required — the motion verdict pass.
     const accepted = geometry.geometry !== null && geometry.geometry.verdict === 'pass' && (!input.motionRequired || (motion !== null && motion.verdict === 'pass'));
@@ -1354,7 +1476,7 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
         : {}
       : { overBound: { maxSamples: overBound.maxSamples, triangles: overBound.triangles } }),
   };
-  return {
+  const report: MeshQualityReport = {
     spec: MESH_QUALITY_REPORT_SPEC,
     operation: 'compare',
     effective,
@@ -1365,4 +1487,6 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
     candidates: candidates.map((c, i) => reportOf(c, candGeometry[i], candidateMotions[i], true)),
     termination: null,
   };
+  // The prepared geometry, pose and reference rows live across calls. A caller may edit a returned report.
+  return prepared === undefined ? report : structuredClone(report);
 }

package/src/motion.ts

@@ -146,8 +146,8 @@ export const MOTION_KEYS = {
   MotionDrawOrderKey: ['t', 'offsets'],
   MotionDrawOrderOffset: ['slot', 'offset'],
   MotionEventKey: ['t', 'name', 'int', 'float', 'string', 'volume', 'balance'],
-  TrackDeriveTurn: ['kind', 'degrees', 'depth', 'carried', 'about'],
-  DeformTurn: ['kind', 'radius', 'depth', 'degrees', 'about', 'envelope'],
+  TrackDeriveTurn: ['kind', 'degrees', 'depth', 'carried', 'about', 'narrowing'],
+  DeformTurn: ['kind', 'radius', 'depth', 'degrees', 'about', 'narrowing', 'envelope'],
   DeformAffine: ['kind', 'scale', 'about', 'envelope'],
   DeformWave: ['kind', 'amplitude', 'wavelength', 'phase', 'along', 'axis', 'envelope'],
   DeformBend: ['kind', 'amount', 'from', 'to', 'power', 'along', 'axis', 'envelope'],
@@ -220,8 +220,8 @@ export const MOTION_TYPES = {
   MotionEventKey: {
     t: 'number', name: 'string', int: 'number', float: 'number', string: 'string', volume: 'number', balance: 'number',
   },
-  TrackDeriveTurn: { kind: 'enum', degrees: 'number', depth: 'mixed', carried: 'number', about: 'number' },
-  DeformTurn: { kind: 'enum', radius: 'number', depth: 'boolean', degrees: 'number', about: 'number', envelope: 'object' },
+  TrackDeriveTurn: { kind: 'enum', degrees: 'number', depth: 'mixed', carried: 'number', about: 'number', narrowing: 'boolean' },
+  DeformTurn: { kind: 'enum', radius: 'number', depth: 'boolean', degrees: 'number', about: 'number', narrowing: 'boolean', envelope: 'object' },
   DeformAffine: { kind: 'enum', scale: 'number[]', about: 'number[]', envelope: 'object' },
   DeformWave: {
     kind: 'enum', amplitude: 'number', wavelength: 'number', phase: 'number', along: 'enum', axis: 'enum', envelope: 'object',

package/src/rig.ts

@@ -471,8 +471,8 @@ export interface RigDepthMap {
    */
   near: 'white' | 'black';
   /**
-   * How many world units the map's full 0..1 range spans, in the attachment's
-   * own units — the number `radius` used to carry.
+   * How many units the map's full 0..1 range spans: setup world units on an
+   * authored mesh, the generator's bind units on a generated mesh.
    *
    * Authored, never measured: 8 bits of level say nothing about scale, so a
    * compiler that picked one would be inventing the depth of the art.
@@ -971,6 +971,8 @@ export interface RigMeshAttachment {
   color?: string;
   /** Build the geometry instead of authoring it — see `RigMeshGenerator`. */
   generator?: RigMeshGenerator;
+  /** A setup-world depth turn over authored geometry; sampled in the part's pixel grid. */
+  depth?: RigDepthMap;
   /** A numbered image series over this one triangulation — see `RigSequence`. */
   sequence?: RigSequence;
 }
@@ -2077,7 +2079,7 @@ export const RIG_KEYS = {
   RigRegionAttachment: ['type', 'name', 'path', 'image', 'x', 'y', 'rotation', 'scaleX', 'scaleY', 'width', 'height', 'color', 'sequence'],
   RigMeshAttachment: [
     'type', 'name', 'path', 'image', 'uvs', 'triangles', 'vertices', 'weights', 'boneIndexing', 'hull', 'edges',
-    'width', 'height', 'color', 'generator', 'sequence',
+    'width', 'height', 'color', 'generator', 'depth', 'sequence',
   ],
   RigLinkedMeshAttachment: [
     'type', 'name', 'path', 'image', 'source', 'slot', 'skin', 'timelines', 'width', 'height', 'color', 'sequence',
@@ -2201,7 +2203,7 @@ export const RIG_TYPES = {
   RigMeshAttachment: {
     type: 'enum', name: 'string', path: 'string', image: 'string', uvs: 'number[]', triangles: 'number[]',
     vertices: 'number[]', weights: 'object[][]', boneIndexing: 'enum', hull: 'number', edges: 'number[]',
-    width: 'number', height: 'number', color: 'string', generator: 'object', sequence: 'object',
+    width: 'number', height: 'number', color: 'string', generator: 'object', depth: 'object', sequence: 'object',
   },
   RigLinkedMeshAttachment: {
     type: 'enum', name: 'string', path: 'string', image: 'string', source: 'string', slot: 'string', skin: 'string',
@@ -2557,6 +2559,7 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): Array<{
             at(binding, 'RigMeshBinding', `${who} weights[${i}][${j}]`, [...here, 'weights', i, j]);
           }
         }
+        at(att.depth, 'RigDepthMap', `${who} depth`, [...here, 'depth']);
         if (!isObj(att.generator)) continue;
         const gen = att.generator;
         const kind = RIG_GENERATOR_KINDS.find((k) => k === gen.kind);

package/src/runtime/curves.ts

@@ -0,0 +1,106 @@
+/**
+ * A keyed timeline compiled once for the runtime poser (issue #1591): its key
+ * times and channel values as the oracle stores them (float32, `CoreKey.time`
+ * and `.values`), each segment's curve kind, and every Bézier segment's
+ * polyline evaluated at load by the oracle's own `bezierPolyline`, so that a
+ * pose evaluates the segment the oracle evaluates and nothing else.
+ *
+ * The two reads a pose makes are the oracle's (`keyIndexAt` and `channelAt`
+ * in `src/core/animation.ts`), operation for operation:
+ *
+ * - **The key at `t`** is the last key whose time is at or before `t`, −1
+ *   before the first. The oracle scans from key 0 every time; the runtime
+ *   walks a per-pose cursor from where the previous pose left it, backwards
+ *   while the key's time is after `t` and forwards while the next one's is
+ *   not. Over key times that never decrease (the reader refuses a key not
+ *   after the one before, and float32 can only make two equal), both find the
+ *   same key for every finite `t`. A `t` that is not finite is refused before
+ *   any search (`RuntimeInputError`): the scan reads −1 for NaN and the
+ *   cursor would read wherever it stood.
+ * - **A channel's value** on the segment from key `i`: the key's own value on
+ *   the last key and after a hold; `v0 + ((t − t0) / (t1 − t0)) · (v1 − v0)`
+ *   on a linear segment; and on a Bézier segment the linear piece of the
+ *   polyline whose end is the first point at or after `t`.
+ *
+ * Nothing here allocates once compiled.
+ */
+import { bezierPolyline, BEZIER_PIECES, type CoreKey } from '../core/animation.ts';
+
+/** A segment's curve, per key. */
+export const CURVE_LINEAR = 0;
+export const CURVE_STEPPED = 1;
+export const CURVE_BEZIER = 2;
+
+/** Numbers in one channel's polyline: the segment's two ends and the nine interior points, each a time and a value. */
+export const POLYLINE = 2 * (BEZIER_PIECES + 1);
+
+/** One compiled timeline. `values` and `polylines` are by key, then by channel. */
+export interface RuntimeCurve {
+  readonly keys: number;
+  readonly channels: number;
+  readonly times: Float64Array;
+  readonly values: Float64Array;
+  readonly kinds: Uint8Array;
+  /** `POLYLINE` numbers per key and channel; filled only where the key starts a Bézier segment. */
+  readonly polylines: Float64Array;
+}
+
+/** A timeline's keys compiled; `channels` is how many values each key carries (0 for an attachment timeline). */
+export function compileCurve(keys: readonly CoreKey[], channels: number): RuntimeCurve {
+  const n = keys.length;
+  const times = new Float64Array(n);
+  const values = new Float64Array(n * channels);
+  const kinds = new Uint8Array(n);
+  const polylines = new Float64Array(n * channels * POLYLINE);
+  for (let i = 0; i < n; i++) {
+    const a = keys[i];
+    times[i] = a.time;
+    for (let c = 0; c < channels; c++) values[i * channels + c] = a.values[c];
+    const curve = a.curve;
+    kinds[i] = curve === 'linear' ? CURVE_LINEAR : curve === 'stepped' ? CURVE_STEPPED : CURVE_BEZIER;
+    if (typeof curve === 'string' || i + 1 >= n) continue;
+    const b = keys[i + 1];
+    for (let c = 0; c < channels; c++) {
+      // The oracle's polyline (`channelAt`): the segment's float32 ends around the recurrence over the numbers as the document states them.
+      const inner = bezierPolyline(a.stated.time, a.stated.values[c], curve[c * 4], curve[c * 4 + 1], curve[c * 4 + 2], curve[c * 4 + 3], b.stated.time, b.stated.values[c]);
+      const o = (i * channels + c) * POLYLINE;
+      polylines[o] = a.time;
+      polylines[o + 1] = a.values[c];
+      for (let q = 0; q < inner.length; q++) polylines[o + 2 + q] = inner[q];
+      polylines[o + POLYLINE - 2] = b.time;
+      polylines[o + POLYLINE - 1] = b.values[c];
+    }
+  }
+  return { keys: n, channels, times, values, kinds, polylines };
+}
+
+/** The last key at or before `t` (−1 before the first), found from `cursors[slot]` and left there — the header's first read. */
+export function keyAt(curve: RuntimeCurve, cursors: Int32Array, slot: number, t: number): number {
+  const times = curve.times;
+  let i = cursors[slot];
+  while (i >= 0 && times[i] > t) i--;
+  while (i + 1 < curve.keys && times[i + 1] <= t) i++;
+  cursors[slot] = i;
+  return i;
+}
+
+/** Channel `c` of the segment starting at key `i` (at or after 0), at `t` — the header's second read. */
+export function channelValue(curve: RuntimeCurve, i: number, c: number, t: number): number {
+  const ch = curve.channels;
+  const values = curve.values;
+  const v0 = values[i * ch + c];
+  if (i + 1 >= curve.keys) return v0;
+  const kind = curve.kinds[i];
+  if (kind === CURVE_STEPPED) return v0;
+  if (kind === CURVE_LINEAR) {
+    const t0 = curve.times[i];
+    return v0 + ((t - t0) / (curve.times[i + 1] - t0)) * (values[(i + 1) * ch + c] - v0);
+  }
+  const p = curve.polylines;
+  const o = (i * ch + c) * POLYLINE;
+  let q = 2;
+  while (q < POLYLINE - 2 && p[o + q] < t) q += 2;
+  const x0 = p[o + q - 2];
+  const y0 = p[o + q - 1];
+  return y0 + ((t - x0) / (p[o + q] - x0)) * (p[o + q + 1] - y0);
+}

package/src/runtime/index.ts

@@ -0,0 +1,84 @@
+/**
+ * rigc's runtime poser (issue #1591): the model document posed in place, for
+ * a player drawing many skeletons a frame — separate from the verification
+ * oracle (`src/core/`) and held equal to it at tolerance 0.
+ *
+ * ## Why there are two posers
+ *
+ * The oracle is the reference. Each of its poses is a pure function of the
+ * document, the skin and the time, returned as a fresh, name-keyed, detached
+ * record — the shape a comparison needs, and the shape the core gate holds to
+ * spine-core 4.3.13 to the last bit. A player that consumes that record every
+ * frame pays for the record: the audit behind issue #1591 measured 175–251
+ * KiB allocated per skeleton per frame, against under half a KiB for the
+ * official runtime. The runtime poser keeps one pose per skeleton, resolves
+ * every name to an index once at load (`compileRuntime`) and overwrites typed
+ * arrays in place (`RuntimePose`), so a steady-state frame allocates nothing.
+ *
+ * It does not re-derive the oracle's rules. Every formula is the oracle's, in
+ * the oracle's order of operations (`./pose.ts`'s header), and the gate is the
+ * oracle itself: `tools/core_gate.ts`'s third dumper poses every model of the
+ * corpus through both at the oracle's samples and compares full doubles at
+ * tolerance 0 (*The runtime poser* there). The oracle is not changed for it.
+ *
+ * ## Stage 1: what it poses, and what it refuses
+ *
+ * Bones and their five inherit modes; the rotate, translate, scale and shear
+ * timelines; a slot's attachment and colour (`rgba`, `rgb`, `alpha`)
+ * timelines; region, mesh, weighted mesh and linked mesh vertices; one- and
+ * two-bone ik and world-space, absolute transform constraints with their
+ * timelines; skin-required bones and constraints under the view's skin. One
+ * animation at full weight from the setup pose, at a time or stepped as a
+ * looping track. Everything else is refused at load by name with the list of
+ * what is missing (`./model.ts`'s header and `RUNTIME_FEATURES`); a consumer
+ * falls back to the oracle for a refused model or animation, so nothing breaks
+ * while coverage grows. Named skin views and their required bones are posed;
+ * to switch, compile the new underSkin/underNoSkin view at load and restore the
+ * animation/time and event cursor with newPose.restore(name, old.trackTime,
+ * old.time). Restoration delivers no already-passed cue. `pose.events` borrows immutable seven-field
+ * deliveries over the last interval, in oracle order, until the next apply/step.
+ *
+ * ```ts
+ * const model = compileRuntime(underNoSkin(readModel(text)));
+ * const pose = new RuntimePose(model);
+ * pose.setAnimation('walk');
+ * pose.step(1 / 60);       // or pose.apply(t)
+ * pose.computeVertices();  // pose.world, pose.light, pose.shown, pose.vertices
+ * ```
+ *
+ * This module is the `rig-c/runtime` entry (`exports` in package.json), which
+ * is **experimental**: not promised until the poser stabilises (RELEASING.md,
+ * *The import surface*). Pure, as all of `src/`, linking nothing from the Spine
+ * runtime package (`RP10`), and safe to bundle for a browser: its value closure
+ * is this directory and `src/core/` (`CUR136`).
+ */
+export {
+  compileRuntime,
+  missingText,
+  RuntimeInputError,
+  RuntimeRefusal,
+  RUNTIME_FEATURES,
+  RUNTIME_STAGE,
+  DRAW_MESH,
+  DRAW_NONE,
+  DRAW_REGION,
+  DRAW_WEIGHTED,
+  LOCAL_FIELD_NAMES,
+  LOCALS,
+  WORLDS,
+  W_A,
+  W_B,
+  W_C,
+  W_D,
+  W_X,
+  W_Y,
+  L_X,
+  L_Y,
+  L_ROTATION,
+  L_SCALE_X,
+  L_SCALE_Y,
+  L_SHEAR_X,
+  L_SHEAR_Y,
+} from './model.ts';
+export type { RuntimeAnimation, RuntimeEvent, RuntimeAttachment, RuntimeFeature, RuntimeMissing, RuntimeModel, RuntimeOptions, RuntimePlant, RuntimeSlot } from './model.ts';
+export { RuntimePose } from './pose.ts';