@rig-c/core 2.71.0 → 2.73.0

package/src/core/events.ts

@@ -33,6 +33,10 @@ import { gridRound } from './index.ts';
 
 /** An event definition, as the model states it (`ModelEvent`): the payload a key falls back to. */
 export interface CoreEventDef {
+  /** Audio metadata retained additively; the five-column oracle row is unchanged. */
+  audio?: string;
+  volume?: number;
+  balance?: number;
   name: string;
   int: number;
   float: number;
@@ -41,6 +45,9 @@ export interface CoreEventDef {
 
 /** One event key, as read: its time (float32) and the payload it fires with, each field resolved. */
 export interface CoreEventKey {
+  /** Audio delivery values, as observed from the public EventTimeline API. */
+  volume?: number;
+  balance?: number;
   time: number;
   name: string;
   int: number;
@@ -55,8 +62,8 @@ const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'obj
 const EVENT_DEF_FIELDS = ['name', 'int', 'float', 'string', 'audio', 'volume', 'balance'] as const;
 const EVENT_KEY_FIELDS = ['time', 'name', 'int', 'float', 'string', 'volume', 'balance'] as const;
 
-function payload(raw: Record<string, unknown>, at: string, problems: string[]): { int?: number; float?: number; string?: string } {
-  const out: { int?: number; float?: number; string?: string } = {};
+function payload(raw: Record<string, unknown>, at: string, problems: string[]): { int?: number; float?: number; string?: string; volume?: number; balance?: number } {
+  const out: { int?: number; float?: number; string?: string; volume?: number; balance?: number } = {};
   if (raw.int !== undefined) {
     if (typeof raw.int !== 'number' || !Number.isInteger(raw.int)) problems.push(`${at}: int is ${JSON.stringify(raw.int)}, not a whole number`);
     else out.int = raw.int;
@@ -69,7 +76,10 @@ function payload(raw: Record<string, unknown>, at: string, problems: string[]):
     if (typeof raw.string !== 'string') problems.push(`${at}: string is ${JSON.stringify(raw.string)}, not a string`);
     else out.string = raw.string;
   }
-  for (const key of ['volume', 'balance'] as const) if (raw[key] !== undefined && (typeof raw[key] !== 'number' || !Number.isFinite(raw[key]))) problems.push(`${at}: ${key} is ${JSON.stringify(raw[key])}, not a finite number`);
+  for (const key of ['volume', 'balance'] as const) if (raw[key] !== undefined) {
+    if (typeof raw[key] !== 'number' || !Number.isFinite(raw[key])) problems.push(`${at}: ${key} is ${JSON.stringify(raw[key])}, not a finite number`);
+    else out[key] = raw[key];
+  }
   return out;
 }
 
@@ -90,7 +100,7 @@ export function readEventDefs(value: unknown, problems: string[]): Map<string, C
     if (raw.audio !== undefined && typeof raw.audio !== 'string') problems.push(`${at} "${raw.name}": audio is ${JSON.stringify(raw.audio)}, not a string`);
     if (out.has(raw.name)) problems.push(`${at}: event "${raw.name}" is declared twice`);
     const p = payload(raw, `${at} "${raw.name}"`, problems);
-    out.set(raw.name, { name: raw.name, int: p.int ?? 0, float: p.float ?? 0, string: p.string ?? '' });
+    out.set(raw.name, { audio: typeof raw.audio === 'string' ? raw.audio : '', volume: p.volume ?? 0, balance: p.balance ?? 0, name: raw.name, int: p.int ?? 0, float: p.float ?? 0, string: p.string ?? '' });
   });
   return out;
 }
@@ -121,7 +131,9 @@ export function readEventKeys(value: unknown, label: string, defs: ReadonlyMap<s
       return;
     }
     const p = payload(raw, at, problems);
-    out.push({ time: Math.fround(typeof t === 'number' && Number.isFinite(t) ? t : 0), name: def.name, int: p.int ?? def.int, float: p.float ?? def.float, string: p.string ?? def.string });
+    // Observed oracle behavior: a voiced key's omitted balance falls back to
+    // the definition's volume, not its balance. A silent event keeps both at 0.
+    out.push({ volume: def.audio ? p.volume ?? def.volume ?? 0 : 0, balance: def.audio ? p.balance ?? def.volume ?? 0 : 0, time: Math.fround(typeof t === 'number' && Number.isFinite(t) ? t : 0), name: def.name, int: p.int ?? def.int, float: p.float ?? def.float, string: p.string ?? def.string });
   });
   return out;
 }

package/src/deformgen.ts

@@ -374,7 +374,7 @@ export function evaluateDeformTransform(
   round: Rounder,
   where: string,
   /**
-   * Per-vertex `z` for this attachment, when its generator named a depth map.
+   * Per-vertex `z` for this attachment, when it or its generator named a depth map.
    * Null when it named none — which is what makes `"depth": true` refusable by
    * name rather than silently falling back to a cylinder.
    */
@@ -448,7 +448,7 @@ export function evaluateDeformTransform(
       if (fromDepth && depth === null) {
         throw new CompileError(
           `${where}: transform ${kind} says "depth": true and this attachment has no depth map. The map is named on ` +
-            'the attachment\'s generator, as `"depth": { "image": …, "near": …, "zScale": … }`, because it describes ' +
+            'an authored attachment or its contour/grid generator, as `"depth": { "image": …, "near": …, "zScale": … }`, because it describes ' +
             'the art rather than this key. Name it there, or give this key a radius.', 'CE_DEFORM_DEPTH_MAP_REQUIRED',
         );
       }

package/src/mesh.ts

@@ -930,7 +930,9 @@ export function segmentsMeet(
   const o2 = o(a, b, d);
   const o3 = o(c, d, a);
   const o4 = o(c, d, b);
-  if (o1 !== o2 && o3 !== o4) return true;
+  // An epsilon-zero orientation is not a strict side of a line. In that case
+  // only the endpoint tests below can establish contact (including the bounds).
+  if (o1 !== 0 && o2 !== 0 && o3 !== 0 && o4 !== 0 && o1 !== o2 && o3 !== o4) return true;
   return onSegment(a, b, c) || onSegment(a, b, d) || onSegment(c, d, a) || onSegment(c, d, b);
 }
 

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/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;
 }
@@ -1122,7 +1124,26 @@ export interface RigBoundingBoxAttachment extends RigVertexGeometry {
  * never ends — it runs to the bottom of the draw order and takes every slot
  * below it with it. rigc refuses a name the rig does not declare.
  */
-export interface RigClippingAttachment extends RigVertexGeometry {
+/** A clipping outline measured from one named attachment's plate. No inferred parameters. */
+export interface RigAlphaClip {
+  slot: string;
+  skin: string;
+  attachment: string;
+  alpha: number;
+  tolerance: number;
+  maxVertices: number;
+}
+
+export interface RigClippingAttachment {
+  /** Authored geometry uses the same named/raw contract as RigVertexGeometry. */
+  vertices?: number[];
+  weights?: RigMeshBinding[][];
+  boneIndexing?: 'name' | 'raw';
+  color?: string;
+  /** Required for authored geometry; derived for alphaClip. */
+  vertexCount?: number;
+  /** Exclusive with authored vertexCount/vertices/weights/boneIndexing. */
+  alphaClip?: RigAlphaClip;
   type: 'clipping';
   /** The runtime's attachment name — see `RigAttachmentName`. Absent, it is the placeholder. */
   name?: RigAttachmentName;
@@ -2077,7 +2098,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',
@@ -2087,7 +2108,8 @@ export const RIG_KEYS = {
   RigMeshBinding: ['bone', 'x', 'y', 'weight'],
   RigSequence: ['count', 'start', 'digits', 'setup'],
   RigBoundingBoxAttachment: ['vertexCount', 'vertices', 'weights', 'boneIndexing', 'color', 'type', 'name'],
-  RigClippingAttachment: ['vertexCount', 'vertices', 'weights', 'boneIndexing', 'color', 'type', 'name', 'end', 'convex', 'inverse'],
+  RigClippingAttachment: ['vertexCount', 'vertices', 'weights', 'boneIndexing', 'color', 'type', 'name', 'end', 'convex', 'inverse', 'alphaClip'],
+  RigAlphaClip: ['slot', 'skin', 'attachment', 'alpha', 'tolerance', 'maxVertices'],
   RigPathAttachment: ['vertexCount', 'vertices', 'weights', 'boneIndexing', 'color', 'type', 'name', 'closed', 'constantSpeed', 'lengths'],
   RigRingGenerator: ['kind', 'hull', 'center', 'inner', 'size', 'bias', 'controls'],
   RigRibbonGenerator: ['kind', 'size', 'rows', 'chain'],
@@ -2201,7 +2223,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',
@@ -2216,8 +2238,9 @@ export const RIG_TYPES = {
   },
   RigClippingAttachment: {
     vertexCount: 'number', vertices: 'number[]', weights: 'object[][]', boneIndexing: 'enum', color: 'string', type: 'enum', name: 'string',
-    end: 'string', convex: 'boolean', inverse: 'boolean',
+    end: 'string', convex: 'boolean', inverse: 'boolean', alphaClip: 'object',
   },
+  RigAlphaClip: { slot: 'string', skin: 'string', attachment: 'string', alpha: 'number', tolerance: 'number', maxVertices: 'number' },
   RigPathAttachment: {
     vertexCount: 'number', vertices: 'number[]', weights: 'object[][]', boneIndexing: 'enum', color: 'string', type: 'enum', name: 'string',
     closed: 'boolean', constantSpeed: 'boolean', lengths: 'number[]',
@@ -2548,6 +2571,7 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): Array<{
         }
         const here = [...base, slot, placeholder];
         at(att, shape, `${who} (${type})`, here);
+        if (type === 'clipping') at(att.alphaClip, 'RigAlphaClip', `${who} alphaClip`, [...here, 'alphaClip']);
         if (att.sequence !== undefined) {
           at(att.sequence, 'RigSequence', `${who} "sequence"`, [...here, 'sequence']);
           checkRigSequence(att, who, where);
@@ -2557,6 +2581,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/index.ts

@@ -21,7 +21,7 @@
  * 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 0: what it poses, and what it refuses
+ * ## 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`)
@@ -32,10 +32,14 @@
  * 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.
+ * 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)), { ignore: ['events'] });
+ * const model = compileRuntime(underNoSkin(readModel(text)));
  * const pose = new RuntimePose(model);
  * pose.setAnimation('walk');
  * pose.step(1 / 60);       // or pose.apply(t)
@@ -76,5 +80,5 @@ export {
   L_SHEAR_X,
   L_SHEAR_Y,
 } from './model.ts';
-export type { RuntimeAnimation, RuntimeAttachment, RuntimeFeature, RuntimeMissing, RuntimeModel, RuntimeOptions, RuntimePlant, RuntimeSlot } from './model.ts';
+export type { RuntimeAnimation, RuntimeEvent, RuntimeAttachment, RuntimeFeature, RuntimeMissing, RuntimeModel, RuntimeOptions, RuntimePlant, RuntimeSlot } from './model.ts';
 export { RuntimePose } from './pose.ts';