@rig-c/core 2.71.0 → 2.72.0

package/docs/AUTHORING.md

@@ -2935,8 +2935,9 @@ rather than being checked afterwards.
 
 #### 3.4.5 `depth` — give every vertex its own z, instead of one cylinder radius
 
-**On a `contour` or a `grid`.** A grid is the one it was built for: a turn
-needs interior vertices to move, and a contour has none of its own.
+**On a `contour` or a `grid` generator, or directly on an authored mesh**
+(including named or raw weighted geometry). A grid supplies interior vertices;
+an authored mesh keeps its existing triangulation and weights.
 
 A `yaw` or `pitch` key (§4.12) turns a part by treating it as painted on a
 cylinder: a vertex `u` off the axis gets `z = √(radius² − u²)`. That is the right
@@ -2954,6 +2955,35 @@ off a greyscale sheet in the part's own pixel grid:
 }
 ```
 
+For authored geometry, put the same block beside `weights` or `vertices`:
+
+```json
+"depth": { "image": "strand_depth.png", "near": "white", "zScale": 12 }
+```
+
+The attachment must name an `image`. Each vertex's **setup world position**
+(the weighted sum of its setup bind positions) is located in the same window
+as the generators: the part is centred on the slot bone's setup world origin,
+x right and y up, while the sheet is in part pixels, x right and y down.
+UVs do not locate these samples. On a scaled atlas page the same drawing-sized
+sheet is read through the existing page-to-drawing conversion. A sheet whose
+size differs from the part is refused by `CE_COMPILE_GREY_SHEET_SIZE_MISMATCH`.
+A top-level `depth` beside a generator is refused; use that generator's depth
+field for generated geometry.
+
+An authored `yaw` or `pitch` key with `depth: true` evaluates in **setup world**,
+including `about` in world units. Its driving-axis displacement is
+`(coordinate - about) * (cos(angle) - 1) - z * sin(angle)`; with
+`narrowing: false` only `-z * sin(angle)` remains. Each rounded world offset is
+written through every influencing bone's inverse setup linear transform.
+Subsequent bone animation and physics carry those bind offsets with the mesh:
+the displacement after posing is the weighted composition of the posed bones
+with their inverse setup transforms, rather than a fixed global translation.
+The reported turn ceiling measures the setup-world triangles on both axes;
+A39 still measures the actual posed artifact. Other transform kinds and meshes
+without this new input keep their existing evaluation spaces and emitted bytes.
+Naming a sheet without a depth turn changes no skeleton or atlas byte.
+
 | Field | Meaning |
 | --- | --- |
 | `image` | **required.** The sheet, relative to the rig's `images` directory, and the **same pixel size as this attachment's `image`**. It is not packed into the atlas — it is a measurement rigc reads at compile time, not art anything draws. Under `--atlas-in` that is still the drawing's size, on a page that declares a `scale:` too: the sheet is read at each vertex's texel position over the scale the atlas states, so one sheet serves the loose parts and every pack of them |
@@ -7330,7 +7360,7 @@ retain the minimal inputs and report that code rather than inventing author data
 | <a id="CE_COMPILE_DEPTH_IMAGE_MISSING"></a>`CE_COMPILE_DEPTH_IMAGE_MISSING` | “&lt;value&gt;: the depth block has no "image"; it is the sheet to sample, relative to the rig's images directory” | State the depth image relative to the rig images directory. |
 | <a id="CE_COMPILE_DEPTH_NEAR_INVALID"></a>`CE_COMPILE_DEPTH_NEAR_INVALID` | “&lt;value&gt;: the depth block says "near": &lt;value&gt;; it is "white" or "black". Both conventions are in use, and a sheet read with the wrong one turns the part inside out with every gate green.” | State near as white or black to declare the sheet convention. |
 | <a id="CE_COMPILE_DEPTH_TONE_SCALE_INVALID"></a>`CE_COMPILE_DEPTH_TONE_SCALE_INVALID` | “&lt;value&gt;: "zScale" is &lt;value&gt;; it is a finite number of world units”<br>“&lt;value&gt;: "zScale" is &lt;value&gt;; it is how many units the map's full range spans, so a positive number. To put the near end at the back, say "near": "black" — a negative scale states the same thing twice and the two can then disagree.”<br>“&lt;value&gt;: depth tone "&lt;value&gt;" is &lt;value&gt;; it is a finite number”<br>“&lt;value&gt;: depth tone "contrast" is &lt;value&gt;; a contrast at or below 0 collapses the range onto the midpoint (or turns it inside out), so the map would describe a flat part. It is a positive number, and 1 leaves the range alone.”<br>“&lt;value&gt;: depth tone "gamma" is &lt;value&gt;; a gamma at or below 0 maps every level to the same nearness, so the map would describe a flat part. It is a positive number, and 1 is the straight line.”<br>Here the values named in the message include: “bias”. | Use finite depth tone values, positive gamma/contrast and a positive finite zScale. |
-| <a id="CE_COMPILE_DEPTH_COVERAGE_INCOMPLETE"></a>`CE_COMPILE_DEPTH_COVERAGE_INCOMPLETE` | “&lt;value&gt;: the depth map "&lt;value&gt;" does not cover &lt;value&gt; of the mesh's &lt;value&gt; vertices — the first is vertex &lt;value&gt; at (&lt;value&gt;, &lt;value&gt;)[ /  in the page's texels, pixel (&lt;value&gt;, &lt;value&gt;) of the drawing-sized sheet]. &lt;value&gt; Sampling anyway would give those vertices the sheet's background depth and fold them away from the turn.”<br>“[A contour mesh puts every vertex ON the silhouette and pushes it out by the margin, so a sheet cut to the art stops short of every one of them. Dilate the sheet past the mesh margin, or lower the margin. / A grid spans the whole part window, corners included, while a sheet is usually cut to the art — so the lattice reaches past it wherever the art does not fill the window. Dilate the sheet to the window, or state "us"/"vs" that keep the lattice inside the art.]” | Supply a depth sheet covering every mesh vertex in the part's drawing-sized pixel grid. |
+| <a id="CE_COMPILE_DEPTH_COVERAGE_INCOMPLETE"></a>`CE_COMPILE_DEPTH_COVERAGE_INCOMPLETE` | “&lt;value&gt;: the depth map "&lt;value&gt;" does not cover &lt;value&gt; of the mesh's &lt;value&gt; vertices — the first is vertex &lt;value&gt; at (&lt;value&gt;, &lt;value&gt;)[ /  in the page's texels, pixel (&lt;value&gt;, &lt;value&gt;) of the drawing-sized sheet]. &lt;value&gt; Sampling anyway would give those vertices the sheet's background depth and fold them away from the turn.”<br>“[A contour mesh puts every vertex ON the silhouette and pushes it out by the margin, so a sheet cut to the art stops short of every one of them. Dilate the sheet past the mesh margin, or lower the margin. / A grid spans the whole part window, corners included, while a sheet is usually cut to the art — so the lattice reaches past it wherever the art does not fill the window. Dilate the sheet to the window, or state "us"/"vs" that keep the lattice inside the art. / The authored setup vertices reach outside the sheet coverage. Extend the sheet to cover their bilinear taps, or correct the setup geometry.]” | Supply a depth sheet covering every mesh vertex in the part's drawing-sized pixel grid. |
 | <a id="CE_COMPILE_MESH_BONE_SETUP_TRANSFORM_MISSING"></a>`CE_COMPILE_MESH_BONE_SETUP_TRANSFORM_MISSING` | “&lt;value&gt;: bone "&lt;value&gt;" has no setup transform” | Correct the bone/setup hierarchy; report a missing compiled transform for a declared bone. |
 | <a id="CE_COMPILE_MESH_BONE_NOT_DECLARED"></a>`CE_COMPILE_MESH_BONE_NOT_DECLARED` | “&lt;value&gt;: bone "&lt;value&gt;" is not in the rig's bone list” | Use a bone name declared in the rig. |
 | <a id="CE_COMPILE_GREY_SHEET_IMAGE_MISSING"></a>`CE_COMPILE_GREY_SHEET_IMAGE_MISSING` | “&lt;value&gt;: the "&lt;value&gt;" block has no image to read” | State the image in the named depth/soft block. |
@@ -7467,7 +7497,7 @@ retain the minimal inputs and report that code rather than inventing author data
 | <a id="CE_COMPILE_SEQUENCE_KEY_INDEX_OUTSIDE_SERIES"></a>`CE_COMPILE_SEQUENCE_KEY_INDEX_OUTSIDE_SERIES` | “&lt;value&gt; (t=&lt;value&gt;): index &lt;value&gt; is past the end of a &lt;value&gt;-frame series (frames 0 to &lt;value&gt;). `Sequence.resolveIndex` clamps it to the last frame, so the key would start on a frame it does not name. `index` is 0-based.” | Use a zero-based index within the frame series. |
 | <a id="CE_COMPILE_DEFORM_TRANSFORM_AND_VERTICES"></a>`CE_COMPILE_DEFORM_TRANSFORM_AND_VERTICES` | “&lt;value&gt; (t=&lt;value&gt;): the key carries both a "transform" and a "vertices" run, and they are two answers to one question. Authored offsets and a stated model do not combine, for the same reason a mesh cannot carry both a "generator" and authored geometry — drop one.”<br>Also: “animation "&lt;value&gt;" deform &lt;value&gt;/&lt;value&gt;/&lt;value&gt;”<br>Here the values named in the message include: “default”. | Use a transform model or authored vertex offsets. |
 | <a id="CE_COMPILE_DEFORM_TRANSFORM_START_INDEX"></a>`CE_COMPILE_DEFORM_TRANSFORM_START_INDEX` | “&lt;value&gt; (t=&lt;value&gt;): the key states a "transform" and a start index. A transform is a model of the whole attachment and is evaluated over all &lt;value&gt; 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.”<br>Also: “animation "&lt;value&gt;" deform &lt;value&gt;/&lt;value&gt;/&lt;value&gt;”<br>Here the values named in the message include: “default”. | Apply a transform over the whole attachment without a start index, or author the partial run. |
-| <a id="CE_COMPILE_DEFORM_TRANSFORM_SETUP_UNRESOLVED"></a>`CE_COMPILE_DEFORM_TRANSFORM_SETUP_UNRESOLVED` | “&lt;value&gt; (t=&lt;value&gt;): a "transform" states where every vertex of this attachment goes, and this one has a vertex the arithmetic cannot place — &lt;value&gt;. Fix the weights, or write the bind-space pairs yourself and start the run with "offset".”<br>“vertex &lt;value&gt;'s &lt;value&gt; weights sum to &lt;value&gt; rather than 1. A stated model becomes a deform run by writing each vertex's world displacement D into every influence as Mᵢ⁻¹·D, which moves the vertex by D·Σwᵢ — so a sum that is not 1 has no displacement that lands it where the model says. A20_MESH_WEIGHTS_COHERENT is the assertion that requires that sum, at the same 1e-3”<br>Also: “animation "&lt;value&gt;" deform &lt;value&gt;/&lt;value&gt;/&lt;value&gt;”<br>Here the values named in the message include: “default”. | Fix weights so setup vertices can be positioned, or author bind-space pairs using offset. |
+| <a id="CE_COMPILE_DEFORM_TRANSFORM_SETUP_UNRESOLVED"></a>`CE_COMPILE_DEFORM_TRANSFORM_SETUP_UNRESOLVED` | “&lt;value&gt; (t=&lt;value&gt;): a "transform" states where every vertex of this attachment goes, and this one has a vertex the arithmetic cannot place — &lt;value&gt;. Fix the weights, or write the bind-space pairs yourself and start the run with "offset".”<br>“vertex &lt;value&gt;'s &lt;value&gt; weights sum to &lt;value&gt; rather than 1. A stated model becomes a deform run by writing each vertex's world displacement D into every influence as Mᵢ⁻¹·D, which moves the vertex by D·Σwᵢ — so a sum that is not 1 has no displacement that lands it where the model says. A20_MESH_WEIGHTS_COHERENT is the assertion that requires that sum, at the same 1e-3”<br>Also: “animation "&lt;value&gt;" deform &lt;value&gt;/&lt;value&gt;/&lt;value&gt;”<br>Here the values named in the message include: “default”.<br>“&lt;value&gt;: depth needs resolved setup positions — &lt;value&gt;” | Fix weights so setup vertices can be positioned, or author bind-space pairs using offset. |
 | <a id="CE_COMPILE_DEFORM_TRANSFORM_OFFSET_COUNT"></a>`CE_COMPILE_DEFORM_TRANSFORM_OFFSET_COUNT` | “&lt;value&gt; (t=&lt;value&gt;): the transform produced &lt;value&gt; numbers for &lt;value&gt; vertices”<br>Also: “animation "&lt;value&gt;" deform &lt;value&gt;/&lt;value&gt;/&lt;value&gt;”<br>Here the values named in the message include: “default”. | Report the transform model and compiler defect: the produced offset count does not match the vertices. |
 | <a id="CE_COMPILE_DEFORM_TRANSFORM_RUN_LENGTH"></a>`CE_COMPILE_DEFORM_TRANSFORM_RUN_LENGTH` | “&lt;value&gt; (t=&lt;value&gt;): the transform expanded to &lt;value&gt; numbers and this attachment's deform array is &lt;value&gt; long”<br>Also: “animation "&lt;value&gt;" deform &lt;value&gt;/&lt;value&gt;/&lt;value&gt;”<br>Here the values named in the message include: “default”. | Report the transform model and compiler defect: the expanded offsets do not match the deform array. |
 | <a id="CE_COMPILE_DEFORM_START_SOURCES_CONFLICT"></a>`CE_COMPILE_DEFORM_START_SOURCES_CONFLICT` | “&lt;value&gt; (t=&lt;value&gt;): a key gives its start as "offset" (an index into the deform array) or as "fromVertex" (a vertex index rigc translates), never both”<br>Also: “animation "&lt;value&gt;" deform &lt;value&gt;/&lt;value&gt;/&lt;value&gt;”<br>Here the values named in the message include: “default”. | Use offset or fromVertex, rather than both. |
@@ -7645,7 +7675,9 @@ retain the minimal inputs and report that code rather than inventing author data
 | <a id="CE_DEFORM_TRANSFORM_OBJECT"></a>`CE_DEFORM_TRANSFORM_OBJECT` | “&lt;where&gt;: "transform" is &lt;JSON.stringify(transform)&gt;; it is an object with a "kind"” | Write transform as an object with a kind. |
 | <a id="CE_DEFORM_TRANSFORM_KIND"></a>`CE_DEFORM_TRANSFORM_KIND` | “&lt;where&gt;: "transform" has kind &lt;JSON.stringify(kind)&gt;; this spec evaluates &lt;DEFORM_TRANSFORM_KINDS.join(', ')&gt;. A model that is none of those is still authorable as a "vertices" run.”<br>Here the values named in the message include: “yaw”, “bend”, “wave”, “pitch”, “affine”. | Choose a supported transform kind, or author the deformation as a vertices run. |
 | <a id="CE_DEFORM_DEPTH_RADIUS_CONFLICT"></a>`CE_DEFORM_DEPTH_RADIUS_CONFLICT` | “&lt;where&gt;: transform &lt;kind&gt; states both "depth": true and a radius &lt;JSON.stringify(t.radius)&gt;. They are two answers to how far forward each vertex sits — a cylinder derives it, a map states it — and a key carrying both leaves a reader unable to say which one the output came from. Drop one.” | Choose depth:true or a radius and remove the other. |
-| <a id="CE_DEFORM_DEPTH_MAP_REQUIRED"></a>`CE_DEFORM_DEPTH_MAP_REQUIRED` | “&lt;where&gt;: transform &lt;kind&gt; 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 the art rather than this key. Name it there, or give this key a radius.” | Declare the attachment generator depth map or give this transform a radius. |
+| <a id="CE_DEFORM_DEPTH_MAP_REQUIRED"></a>`CE_DEFORM_DEPTH_MAP_REQUIRED` | “&lt;where&gt;: transform &lt;kind&gt; says "depth": true and this attachment has no depth map. The map is named on 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.” | Declare the authored attachment or contour/grid generator depth map, or give this transform a radius. |
+| <a id="CE_COMPILE_DEPTH_AUTHORED_REQUIRED"></a>`CE_COMPILE_DEPTH_AUTHORED_REQUIRED` | “&lt;where&gt;: attachment "depth" describes authored geometry; a generated mesh states its depth on the contour or grid generator instead” | Put depth on the contour/grid generator or remove the generator and author the geometry. |
+| <a id="CE_COMPILE_DEPTH_IMAGE_REQUIRED"></a>`CE_COMPILE_DEPTH_IMAGE_REQUIRED` | “&lt;where&gt;: an authored mesh with "depth" needs an "image" to locate the part's pixel grid” | Name the part image the sheet describes. |
 | <a id="CE_DEFORM_DEPTH_SAMPLE_COUNT"></a>`CE_DEFORM_DEPTH_SAMPLE_COUNT` | “&lt;where&gt;: transform &lt;kind&gt; has &lt;depth.length&gt; sampled depths for &lt;count&gt; vertices” | Report this compiler defect with the inputs and printed sampled-depth and vertex counts; do not edit generated samples. |
 | <a id="CE_DEFORM_RADIUS_POSITIVE"></a>`CE_DEFORM_RADIUS_POSITIVE` | “&lt;where&gt;: transform &lt;kind&gt; has radius &lt;radius&gt;; it is the radius of the cylinder the part is painted on, so a positive number” | State a positive cylinder radius. |
 | <a id="CE_DEFORM_VERTEX_OUTSIDE_CYLINDER"></a>`CE_DEFORM_VERTEX_OUTSIDE_CYLINDER` | “&lt;where&gt;: transform &lt;kind&gt; has radius &lt;radius&gt;, and vertex &lt;v&gt; sits at &lt;kind === 'yaw' ? 'x' : 'y'&gt;=&lt;setup[2 * v + along]&gt;, which is &lt;round(Math.abs(u) - radius)&gt; past it (about=&lt;about&gt;). The cylinder has no surface there, so its depth would be 0 and the projection would be a different model at that vertex. Raise the radius to where the part actually sits, or move the vertex.” | Raise radius to include the measured vertex or move that vertex within the cylinder. |
@@ -7749,7 +7781,7 @@ retain the minimal inputs and report that code rather than inventing author data
 
 | Code | Fixed message text and alternatives | What to change |
 | --- | --- | --- |
-| <a id="CE_KEYS_UNKNOWN_FIELD"></a>`CE_KEYS_UNKNOWN_FIELD` | “&lt;where&gt;: &lt;what&gt; has &lt;strays.length === 1 ? 'a key' : `${strays.length} keys`&gt; this compiler does not read: &lt;named.join(', ')&gt;. Nothing reads such a key, so it would be dropped from the emitted skeleton in silence — fix the spelling or remove it. {This shape has no fields at all. / Known here: &lt;[...known].sort().join(', ')&gt;.}”<br>“{"&lt;key&gt;" / "&lt;key&gt;" (did you mean &lt;near.map((n) =&gt; `"${n}"`).join(', ')&gt;?)}”<br>Also: “skin "&lt;value&gt;" slot "&lt;value&gt;" attachment "&lt;value&gt;"”<br>“&lt;value&gt; generator.bones[&lt;value&gt;]”<br>“{constraint "&lt;value&gt;" / constraints[&lt;value&gt;]}”<br>“&lt;value&gt;.transform.envelope”<br>“&lt;value&gt; weights[&lt;value&gt;][&lt;value&gt;]”<br>“invariants.deformMayFold[&lt;value&gt;]”<br>“animations."&lt;value&gt;"”<br>“&lt;value&gt;.offsets[&lt;value&gt;]”<br>“{stop "&lt;value&gt;" / stops[&lt;value&gt;]}”<br>“&lt;value&gt; properties."&lt;value&gt;".to."&lt;value&gt;"”<br>“this rig spec”<br>“&lt;value&gt;.derive”<br>“setup."&lt;value&gt;"”<br>“physics."&lt;value&gt;"”<br>“&lt;value&gt;'s "lower"”<br>“&lt;value&gt; "sequence"”<br>“&lt;value&gt; generator.bias”<br>“&lt;value&gt; generator.depth”<br>“&lt;value&gt;.events[&lt;value&gt;]”<br>“&lt;value&gt;.tracks[&lt;value&gt;]”<br>“invariants.axes[&lt;value&gt;]”<br>“&lt;value&gt; generator.falloff”<br>“&lt;value&gt;.drawOrder[&lt;value&gt;]”<br>“&lt;value&gt; generator.influence”<br>“invariants.detached[&lt;value&gt;]”<br>“{slot "&lt;value&gt;" / slots[&lt;value&gt;]}”<br>“invariants.consumerDrivenMix[&lt;value&gt;]”<br>“event "&lt;value&gt;"”<br>“&lt;value&gt;'s "from"”<br>“this motion spec”<br>“{absent / &lt;value&gt;}”<br>“{region / &lt;value&gt;}”<br>“&lt;value&gt;.keys[&lt;value&gt;]”<br>“&lt;value&gt; generator.soft”<br>“{linkedmesh / &lt;value&gt;}”<br>“&lt;value&gt;.deform[&lt;value&gt;]”<br>“&lt;value&gt;.sequence[&lt;value&gt;]”<br>“&lt;value&gt; generator (&lt;value&gt;)”<br>“{bone "&lt;value&gt;" / bones[&lt;value&gt;]}”<br>Here the values named in the message include: “uvs”, “mixX”, “blend”, “scaleX”, “groups”, “radius”, “images”, “axisBone”, “maxBones”, “massBone”, “softness”, “timelines”, “archetype”, “rotateMode”, “windGlobal”, “localTarget”, “spacingMode”, “positionMode”, “inertiaGlobal”, “dampingGlobal”, “gravityGlobal”, “strengthGlobal”, “skeleton.stageBox”, “invariants.idleDrivesMeshes”, “ik”, “lag”, “why”, “cut”, “fps”, “icon”, “dark”, “cols”, “kind”, “hull”, “cell”, “path”, “loop”, “mask”, “ease”, “ramp”, “note”, “mode”, “size”, “rows”, “mixY”, “alpha”, “pairs”, “inner”, “curve”, “limit”, “edges”, “float”, “start”, “audio”, “along”, “clamp”, “width”, “skins”, “links”, “chain”, “phase”, “about”, “power”, “count”, “color”, “gamma”, “index”, “delay”, “shearY”, “source”, “convex”, “target”, “amount”, “volume”, “shearX”, “slider”, “string”, “center”, “parent”, “closed”, “zScale”, “inward”, “margin”, “across”, “height”, “digits”, “scaleY”, “anchor”, “degrees”, “inverse”, “stretch”, “easings”, “against”, “default”, “inherit”, “lengths”, “carried”, “balance”, “stagger”, “outward”, “through”, “vertices”, “axis_deg”, “contrast”, “compress”, “notUnder”, “property”, “duration”, “controls”, “additive”, “rotation”, “triangles”, “mixScaleY”, “mixScaleX”, “mixShearY”, “tolerance”, “mixRotate”, “meshSlots”, “minWeight”, “mixGlobal”, “amplitude”, “massGlobal”, “meshCenter”, “fromVertex”, “slotWindow”, “wavelength”, “"skeleton"”, “attachments”, “vertexCount”, “maxVertices”, “localSource”, “"invariants"”, “bendPositive”, “boneIndexing”, “constantSpeed”, “meshTriangles”, “referenceScale”, “narrowing”. | Fix each printed stray key's spelling using the suggested or known names, or remove it. |
+| <a id="CE_KEYS_UNKNOWN_FIELD"></a>`CE_KEYS_UNKNOWN_FIELD` | “&lt;where&gt;: &lt;what&gt; has &lt;strays.length === 1 ? 'a key' : `${strays.length} keys`&gt; this compiler does not read: &lt;named.join(', ')&gt;. Nothing reads such a key, so it would be dropped from the emitted skeleton in silence — fix the spelling or remove it. {This shape has no fields at all. / Known here: &lt;[...known].sort().join(', ')&gt;.}”<br>“{"&lt;key&gt;" / "&lt;key&gt;" (did you mean &lt;near.map((n) =&gt; `"${n}"`).join(', ')&gt;?)}”<br>Also: “skin "&lt;value&gt;" slot "&lt;value&gt;" attachment "&lt;value&gt;"”<br>“&lt;value&gt; generator.bones[&lt;value&gt;]”<br>“{constraint "&lt;value&gt;" / constraints[&lt;value&gt;]}”<br>“&lt;value&gt;.transform.envelope”<br>“&lt;value&gt; weights[&lt;value&gt;][&lt;value&gt;]”<br>“invariants.deformMayFold[&lt;value&gt;]”<br>“animations."&lt;value&gt;"”<br>“&lt;value&gt;.offsets[&lt;value&gt;]”<br>“{stop "&lt;value&gt;" / stops[&lt;value&gt;]}”<br>“&lt;value&gt; properties."&lt;value&gt;".to."&lt;value&gt;"”<br>“this rig spec”<br>“&lt;value&gt;.derive”<br>“setup."&lt;value&gt;"”<br>“physics."&lt;value&gt;"”<br>“&lt;value&gt;'s "lower"”<br>“&lt;value&gt; "sequence"”<br>“&lt;value&gt; generator.bias”<br>“&lt;value&gt; generator.depth”<br>“&lt;value&gt; depth”<br>“&lt;value&gt;.events[&lt;value&gt;]”<br>“&lt;value&gt;.tracks[&lt;value&gt;]”<br>“invariants.axes[&lt;value&gt;]”<br>“&lt;value&gt; generator.falloff”<br>“&lt;value&gt;.drawOrder[&lt;value&gt;]”<br>“&lt;value&gt; generator.influence”<br>“invariants.detached[&lt;value&gt;]”<br>“{slot "&lt;value&gt;" / slots[&lt;value&gt;]}”<br>“invariants.consumerDrivenMix[&lt;value&gt;]”<br>“event "&lt;value&gt;"”<br>“&lt;value&gt;'s "from"”<br>“this motion spec”<br>“{absent / &lt;value&gt;}”<br>“{region / &lt;value&gt;}”<br>“&lt;value&gt;.keys[&lt;value&gt;]”<br>“&lt;value&gt; generator.soft”<br>“{linkedmesh / &lt;value&gt;}”<br>“&lt;value&gt;.deform[&lt;value&gt;]”<br>“&lt;value&gt;.sequence[&lt;value&gt;]”<br>“&lt;value&gt; generator (&lt;value&gt;)”<br>“{bone "&lt;value&gt;" / bones[&lt;value&gt;]}”<br>Here the values named in the message include: “uvs”, “mixX”, “blend”, “scaleX”, “groups”, “radius”, “images”, “axisBone”, “maxBones”, “massBone”, “softness”, “timelines”, “archetype”, “rotateMode”, “windGlobal”, “localTarget”, “spacingMode”, “positionMode”, “inertiaGlobal”, “dampingGlobal”, “gravityGlobal”, “strengthGlobal”, “skeleton.stageBox”, “invariants.idleDrivesMeshes”, “ik”, “lag”, “why”, “cut”, “fps”, “icon”, “dark”, “cols”, “kind”, “hull”, “cell”, “path”, “loop”, “mask”, “ease”, “ramp”, “note”, “mode”, “size”, “rows”, “mixY”, “alpha”, “pairs”, “inner”, “curve”, “limit”, “edges”, “float”, “start”, “audio”, “along”, “clamp”, “width”, “skins”, “links”, “chain”, “phase”, “about”, “power”, “count”, “color”, “gamma”, “index”, “delay”, “shearY”, “source”, “convex”, “target”, “amount”, “volume”, “shearX”, “slider”, “string”, “center”, “parent”, “closed”, “zScale”, “inward”, “margin”, “across”, “height”, “digits”, “scaleY”, “anchor”, “degrees”, “inverse”, “stretch”, “easings”, “against”, “default”, “inherit”, “lengths”, “carried”, “balance”, “stagger”, “outward”, “through”, “vertices”, “axis_deg”, “contrast”, “compress”, “notUnder”, “property”, “duration”, “controls”, “additive”, “rotation”, “triangles”, “mixScaleY”, “mixScaleX”, “mixShearY”, “tolerance”, “mixRotate”, “meshSlots”, “minWeight”, “mixGlobal”, “amplitude”, “massGlobal”, “meshCenter”, “fromVertex”, “slotWindow”, “wavelength”, “"skeleton"”, “attachments”, “vertexCount”, “maxVertices”, “localSource”, “"invariants"”, “bendPositive”, “boneIndexing”, “constantSpeed”, “meshTriangles”, “referenceScale”, “narrowing”. | Fix each printed stray key's spelling using the suggested or known names, or remove it. |
 | <a id="CE_KEYS_NUMBER_FLOAT32_FINITE"></a>`CE_KEYS_NUMBER_FLOAT32_FINITE` | “&lt;where&gt;: &lt;place(path)&gt; is &lt;String(node)&gt;; a number in this file is finite at float32 precision, at most ±&lt;String(FLOAT32_MAX)&gt;, because the skeleton is written as float32 — past that it would be emitted as Infinity, which JSON writes as null, a value the file never stated.&lt;why&gt;”<br>“{ / { This one is finite as a double and has no float32 but Infinity. /  JSON has no spelling for Infinity: a literal past ±1.7976931348623157e308, such as 1e309, parses to it.}}” | State a finite number whose float32 rounding stays finite; inspect the printed path and magnitude. |
 | <a id="CE_KEYS_FIELD_VALUE_TYPE"></a>`CE_KEYS_FIELD_VALUE_TYPE` | “&lt;where&gt;: &lt;visit.name([key, ...wrong.tail])&gt; is &lt;typeFound(wrong.value)&gt;; &lt;wrong.required&gt; is required”<br>“a boolean (true or false)”<br>“a number”<br>“a number or null”<br>“a string”<br>“a string or null”<br>“an array of arrays of numbers”<br>“an array of numbers”<br>“an array of numbers, or null”<br>“an array of strings”<br>“an object whose every value is a string or null”<br>“an object whose every value is an array of numbers”<br>“an object whose every value is an array of strings” | Replace the named field or element with the required JSON type printed in the message. |
 | <a id="CE_KEYS_ENUM_VALUE"></a>`CE_KEYS_ENUM_VALUE` | “&lt;where&gt;: &lt;visit.name([key])&gt; is &lt;JSON.stringify(value) ?? String(value)&gt;; one of &lt;rule.set.map((name) =&gt; JSON.stringify(name)).join(', ')&gt; — &lt;rule.readAs&gt;”<br>“anything else was read as a ribbon by the mesh checks and as a ring by the control-bone reader and the geometry builder, so the refusal it got named a fault the part did not have”<br>“anything else was read as no rotation source, and the bone was emitted without the setup rotation it asked for”<br>“anything else was read as the default "name" in silence: a weighted "vertices" run was refused as unflagged, and every other attachment built byte for byte as if the key were absent” | Choose one of the printed names for the named field; the readAs explanation describes why another spelling changes its meaning. |
@@ -12491,7 +12523,7 @@ nonselected output is the stored source geometry through the unchanged setup
 matrices; it does not borrow a different selection's deform. The control
 checks both results and the source of the difference, without an epsilon.
 
-## 15. Posing in place for a player — the runtime poser (stage 0)
+## 15. Posing in place for a player — the runtime poser (stage 1)
 
 rigc poses a model document twice over, on purpose (issue #1591). The **oracle**
 (`src/core/`) is the reference: each pose is a pure function of the document,
@@ -12526,17 +12558,43 @@ exact resolved table identity `(skin, model.slots[attachment.slot].name, placeho
 The display `name` may be shared by different placeholders; it is never a table
 key to guess the source from. These load-time strings do not change the pose path.
 
-| | what stage 0 poses |
+| | what stage 1 poses |
 | --- | --- |
 | bones | local and world transforms, all five inherit modes, skin-required bones under the view's skin (an inactive bone is zeros, as the oracle poses it) |
 | timelines | `rotate`, `translate(x/y)`, `scale(x/y)`, `shear(x/y)`; a slot's `attachment`, `rgba`, `rgb` and `alpha`; ik and transform timelines; linear, stepped and Bézier keys, each read from a per-pose key cursor |
 | constraints | one- and two-bone ik; world-space, absolute transform constraints; the document's order, each followed by the bones below what it moved posed again |
 | vertices | regions, meshes, weighted meshes and linked meshes, written into the pose's buffer |
+| skins and events | named/no-skin views with their skin-required bones and constraints; event delivery in key order over `(last, time]`, tail then head across a wrap |
 | time | one animation at full weight from the setup pose, at a time (`apply`) or stepped as a looping track (`step`, the track time wrapped by the duration as `openTrack` wraps it) |
 
+Skin switching is a load-time view change: compile `underSkin(document, name)`
+(or `underNoSkin(document)`), create the replacement `RuntimePose`, then call
+`replacement.restore(animationName, oldPose.trackTime, oldPose.time)`. Restore
+carries both clocks **and the event cursor**: its event list is empty, a key at
+or before that restored animation time is not fired again, and later keys and
+subsequent loops still deliver normally. Do not restore by setting trackTime and
+calling apply: setAnimation starts the event cursor at −1, so that sequence
+replays already-passed cues. `restore` refuses non-finite times by name.
+The old buffers belong to the old view; do not keep drawing them as the new
+skin. An ambiguous merged `all` view still refuses `skin-conflict`; that refusal
+does not reject either named view.
+
+Read `pose.events` immediately after `apply`/`step`. It is a reused borrowed list
+of immutable load-time records: `name`, float32 key `time`, `int`, `float`,
+`string`, `volume`, `balance`. Duplicate-time keys keep their authored order.
+The interval and wrap rules are the oracle's `openTrack` rules; a new animation
+starts at previous event time −1, so an apply at 0 includes its zero-time keys.
+The list is replaced on the next pose; retain copies only when needed. Delivery
+itself reuses records and list storage. The legacy five-column oracle event row
+is unchanged. Public `EventTimeline` observations also hold the audio details:
+silent keys keep volume/balance at 0; on a voiced key an omitted balance falls
+back to the definition's **volume**, matching the measured runtime rather than
+inventing a correction. An explicit `ignore: ['events']` diagnostic still mutes
+the list; normal compilation never does.
+
 **Everything else is refused at load, by name.** `RuntimeRefusal.missing` lists
 every construct met, each `{ feature, detail, animation }`, and the message
-reads `not posed by the runtime poser (stage 0), N construct(s) missing:
+reads `not posed by the runtime poser (stage 1), N construct(s) missing:
 <feature>: <detail>; …`. A model-level feature refuses the whole model; an
 animation-level one refuses that animation alone (`model.refused`;
 `model.animation(name)` and `setAnimation(name)` throw its refusal) and every
@@ -12545,7 +12603,6 @@ refused: nothing is posed approximately.
 
 | feature | refuses | what it is |
 | --- | --- | --- |
-| `skin` | the model | a skin other than `default` |
 | `path-constraint`, `physics-constraint`, `slider-constraint` | the model | a constraint of that kind |
 | `local-transform`, `additive-transform` | the model | a transform constraint with `localSource` or `localTarget`, or `additive` |
 | `inactive-constrained-bone` | the model | an applied ik or transform constraint naming a bone the view leaves inactive (what the oracle writes there depends on the pass before) |
@@ -12554,7 +12611,6 @@ refused: nothing is posed approximately.
 | `skin-conflict` | as above | a placeholder the skins fill differently |
 | `oracle-absent` | the model | a pose the oracle itself leaves out (`constraintsAbsentWhy`) |
 | `inherit-timeline`, `deform-timeline`, `sequence-timeline`, `draw-order-timeline`, `dark-colour-timeline` | the animation | a timeline of that kind (`dark-colour` is `rgba2` / `rgb2`) |
-| `events` | the animation, unless `ignore: ['events']` | event keys. Events move no pose, so a consumer that reads none may ask for them to be ignored and is handed a poser that fires none; without the request a dropped cue would be silent |
 
 A call it cannot answer throws `RuntimeInputError`, naming the call:
 `apply: no animation is set (setAnimation first)`, `animation "x" is not one of
@@ -12577,3 +12633,21 @@ side here. The selftest's `runtime-poser` suite holds the gate to its plants (a
 refused feature smuggled through — each caught by name), a seeded population of
 every construct above, the looping step against `openTrack`, and a steady-state
 frame measured at 0 bytes with the collector off.
+
+## 16. Compare sequential mesh candidates against one motion reference
+
+Programmatic callers that gate candidates one at a time can import
+`prepareMotionReference` and `comparePreparedMotion` from `rig-c/meshcompare`.
+Pass the one-shot `MotionComparisonInput` without `candidates` to preparation,
+then pass each complete input with its candidate list to comparison. The handle
+reuses the reference's parsed build, art samples, carriers and poses only while
+the reference model text, schedule, attachments (including mask alpha bytes),
+art-fit bounds and motion options match exactly. A changed bound field, even
+`+0` to `-0`, throws `MeshReductionError` with
+`COMPARE_PREPARED_MISMATCH` naming the field; a forged handle throws
+`COMPARE_PREPARED_HANDLE`. Prepare a new handle for a different selection or
+held-out schedule. Returned reports are detached from the prepared state, and
+the one-shot `compareMeshesInMotion` retains its report and refusal contract.
+The full comparison contract and its input types are in the repository's
+[MESH_REDUCTION.md](https://github.com/rig-c/core/blob/main/docs/MESH_REDUCTION.md#the-comparison-as-implemented-stage-c1),
+which is not shipped in the package.

package/package.json

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

package/src/compile.ts

@@ -3011,7 +3011,7 @@ 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 }>();
   // 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>();
@@ -3729,6 +3729,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 +3737,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 });
@@ -4367,7 +4369,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
@@ -5755,7 +5757,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 +5840,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 +5879,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 +6241,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 +6281,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 +6366,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 +6409,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 +8778,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 +8812,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 +8859,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 +8931,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 +9107,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 +9133,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 +9144,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 +9182,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 +9202,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/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/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;
 }
@@ -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/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';

package/src/runtime/model.ts

@@ -1,5 +1,5 @@
 /**
- * The runtime poser's load-time half (issue #1591, stage 0): a skin view of
+ * The runtime poser's load-time half (issue #1591, stage 1): a skin view of
  * the compiled model (`readModel`, then `underSkin` / `underNoSkin` — the
  * oracle's reader and its views, read and never written) compiled once into
  * index-resolved bones and slots, a constraint plan, compiled timelines and
@@ -12,8 +12,7 @@
  * (`RuntimeMissing`), and:
  *
  * - **refuses the model** (`RuntimeRefusal`, every missing feature listed)
- *   when one is a property of the whole model — a skin other than `default`, a
- *   path, physics or slider constraint, a transform constraint reading or
+ *   when one is a property of the whole model — a path, physics or slider constraint, a transform constraint reading or
  *   writing local values or adding (`localSource`, `localTarget`,
  *   `additive`), an ik or transform constraint over a bone the view leaves
  *   inactive, a world-space transform onto a `noScale` or
@@ -23,16 +22,15 @@
  * - **refuses an animation** (`RuntimeModel.refused`; `animation(name)`
  *   throws the same `RuntimeRefusal`) when the construct is the animation's
  *   — an `inherit` timeline, a deform or sequence timeline, a draw-order
- *   timeline, event keys, a dark-colour (`rgba2`, `rgb2`) timeline, or an
+ *   timeline, a dark-colour (`rgba2`, `rgb2`) timeline, or an
  *   attachment key showing a clipping attachment or a region with no atlas
  *   rectangle. Every other animation of the model is posed.
  *
- * `RUNTIME_FEATURES` is the closed list of what can be named. Events are the
- * one construct that moves no pose, so they alone can be ignored on request
- * (`RuntimeOptions.ignore`): a consumer that reads no event says so, and is
- * then handed a poser that fires none. Without the request an animation with
- * event keys is refused, because a poser that dropped them silently would be
- * a player that misses its cues and reports nothing.
+ * `RUNTIME_FEATURES` is the closed list of what can be named. Stage 1 reads
+ * named/no-skin views and delivers event keys, with immutable payloads compiled
+ * at load. `ignore: ['events']` remains an explicit diagnostic opt-out; it is
+ * never the default. A merged view with conflicting attachments still refuses
+ * by name, as the oracle itself cannot resolve that view without file order.
  *
  * ## What the oracle decides, the runtime reads
  *
@@ -48,18 +46,16 @@
  * no randomness, no I/O.
  */
 import type { ModelVertices } from '../model.ts';
-import { activeBones, constraintRecords, CORE_REGION_KINDS, foldInheritMode, readBlend, readColour, shownAttachment, shownRow, sourceOfDoc, type CompiledDocument, type CoreAnimation, type CoreBlendMode } from '../core/index.ts';
+import { activeBones, constraintRecords, CORE_REGION_KINDS, foldInheritMode, readBlend, readColour, shownAttachment, shownRow, sourceOfDoc, underSkin, type CompiledDocument, type CoreAnimation, type CoreBlendMode } from '../core/index.ts';
 import { constraintInactiveWhy, constraintsAbsentWhy, TRANSFORM_PROPERTIES, type CoreIkRecord, type CoreTransformRecord } from '../core/constraints.ts';
-import { CORE_DEFAULT_SKIN } from '../core/skins.ts';
 import { RUNTIME_PI } from '../core/world.ts';
 import { compileCurve, type RuntimeCurve } from './curves.ts';
 
 /** The stage of issue #1591 this poser implements. */
-export const RUNTIME_STAGE = 0;
+export const RUNTIME_STAGE = 1;
 
 /** Every construct the runtime poser can refuse, by the name its refusals carry. */
 export const RUNTIME_FEATURES = [
-  'skin',
   'path-constraint',
   'physics-constraint',
   'slider-constraint',
@@ -75,7 +71,6 @@ export const RUNTIME_FEATURES = [
   'deform-timeline',
   'sequence-timeline',
   'draw-order-timeline',
-  'events',
   'dark-colour-timeline',
 ] as const;
 export type RuntimeFeature = (typeof RUNTIME_FEATURES)[number];
@@ -124,6 +119,12 @@ export interface RuntimePlant {
   readonly admit?: readonly RuntimeFeature[];
   /** The update order's scratch sized by the bone count instead of the longest target list: the short-buffer plant. */
   readonly scratchByBones?: boolean;
+  /** Wrong-skin source selected by a control, never by a consumer. */
+  readonly attachmentSkin?: string;
+  /** Drops a key at zero on a wrap, the event boundary plant. */
+  readonly eventWrapOffByOne?: boolean;
+  /** The old restore behavior, which repeats keys up to the restored time. */
+  readonly restoreEventsFromStart?: boolean;
 }
 
 // A bone's local values, seven per bone.
@@ -277,6 +278,17 @@ export interface RuntimeConstraintTimeline {
   readonly flags: Uint8Array | null;
 }
 
+/** One immutable event delivery, reused by every pose of this model. */
+export interface RuntimeEvent {
+  readonly name: string;
+  readonly time: number;
+  readonly int: number;
+  readonly float: number;
+  readonly string: string;
+  readonly volume: number;
+  readonly balance: number;
+}
+
 /** One covered animation, compiled. */
 export interface RuntimeAnimation {
   readonly name: string;
@@ -287,12 +299,16 @@ export interface RuntimeAnimation {
   readonly constraints: ReadonlyArray<RuntimeConstraintTimeline | null>;
   /** How many key cursors a pose keeps for it. */
   readonly cursors: number;
-  /** Event keys it holds — 0 unless the consumer asked for events to be ignored. */
+  /** Number of authored event keys (including an explicitly muted diagnostic). */
   readonly events: number;
+  readonly eventKeys: readonly RuntimeEvent[];
 }
 
 /** The compiled model a pose is made of (`compileRuntime`). Read-only once built. */
 export interface RuntimeModel {
+  /** Control-only boundary defect; fixed at load. */
+  readonly eventWrapOffByOne: boolean;
+  readonly restoreEventsFromStart: boolean;
   readonly doc: CompiledDocument;
   readonly boneNames: readonly string[];
   readonly parents: Int32Array;
@@ -365,7 +381,6 @@ export function compileRuntime(doc: CompiledDocument, options: RuntimeOptions =
   const refusals = new Refusals(new Set(plant.admit ?? []));
   const ignoreEvents = (options.ignore ?? []).includes('events');
 
-  if (doc.skins.some((k) => k.name !== CORE_DEFAULT_SKIN)) refusals.note('skin', `the document declares skins [${doc.skins.map((k) => k.name).join(', ')}]; stage ${RUNTIME_STAGE} poses the default skin alone`);
   const absentWhy = constraintsAbsentWhy(doc);
   if (absentWhy !== null) refusals.note('oracle-absent', `the oracle leaves the bones out: ${absentWhy}`);
 
@@ -440,6 +455,7 @@ export function compileRuntime(doc: CompiledDocument, options: RuntimeOptions =
   const attachments: RuntimeAttachment[] = [];
   let vertexCount = 0;
   const sourceOf = sourceOfDoc(doc);
+  const attachmentView = plant.attachmentSkin === undefined ? doc : underSkin(doc, plant.attachmentSkin);
   /** Per slot, each placeholder's attachment index (−1 shows nothing) and what it misses, resolved once and its refusal noted for every animation that shows it. */
   const resolvedBySlot = doc.slots.map(() => new Map<string | null, { index: number; missing: readonly [RuntimeFeature, string] | null }>());
   const resolve = (si: number, placeholder: string | null, animation: string | null): number => {
@@ -454,7 +470,7 @@ export function compileRuntime(doc: CompiledDocument, options: RuntimeOptions =
   };
   const resolveRecord = (si: number, placeholder: string | null): { index: number; missing: readonly [RuntimeFeature, string] | null } => {
     const slot = doc.slots[si];
-    const shown = placeholder === null ? null : shownAttachment(doc, slot, placeholder);
+    const shown = placeholder === null ? null : shownAttachment(attachmentView, slot, placeholder);
     if (shown === null) return { index: -1, missing: null };
     if ('conflict' in shown) return { index: -1, missing: ['skin-conflict', `slot "${slot.name}" placeholder "${placeholder}" is filled by skins that disagree`] };
     const row = shownRow(shown);
@@ -538,6 +554,8 @@ export function compileRuntime(doc: CompiledDocument, options: RuntimeOptions =
   if (refusals.model.length > 0) throw new RuntimeRefusal(refusals.model);
   const names = doc.animations.map((a) => a.name);
   return {
+    eventWrapOffByOne: plant.eventWrapOffByOne === true,
+    restoreEventsFromStart: plant.restoreEventsFromStart === true,
     doc,
     boneNames: doc.bones.map((b) => b.name),
     parents,
@@ -667,7 +685,6 @@ function compileAnimation(
   if (deform.length > 0) refusals.note('deform-timeline', `${deform.length} deform timeline(s): ${deform.slice(0, 3).map((a) => `${a.skin}/${a.slot}/${a.attachment}`).join(', ')}${deform.length > 3 ? ', …' : ''}`, name);
   if (sequence.length > 0) refusals.note('sequence-timeline', `${sequence.length} sequence timeline(s): ${sequence.slice(0, 3).map((a) => `${a.skin}/${a.slot}/${a.attachment}`).join(', ')}${sequence.length > 3 ? ', …' : ''}`, name);
   if (tl.drawOrder.length > 0) refusals.note('draw-order-timeline', `${tl.drawOrder.length} draw-order key(s)`, name);
-  if (tl.events.length > 0 && !ignoreEvents) refusals.note('events', `${tl.events.length} event key(s); a poser that fires none is handed out only on request (ignore: ['events'])`, name);
 
   const lastBy = <T extends { name: string }>(targets: readonly T[]): Map<string, T> => new Map(targets.map((t) => [t.name, t]));
   const bones: RuntimeBoneTimeline[] = [];
@@ -715,5 +732,5 @@ function compileAnimation(
       constraintTimelines[c.index] = { constraint: c.index, curve: compileCurve(keyed.keys, TRANSFORM_PROPERTIES.length), cursor: cursors++, flags: null };
     }
   }
-  return { name, duration: tl.duration, bones, slots: slotTimelines, constraints: constraintTimelines, cursors, events: tl.events.length };
+  return { name, duration: tl.duration, bones, slots: slotTimelines, constraints: constraintTimelines, cursors, events: tl.events.length, eventKeys: Object.freeze(ignoreEvents ? [] : tl.events.map(key => Object.freeze({ name: key.name, time: key.time, int: key.int, float: key.float, string: key.string, volume: key.volume ?? 0, balance: key.balance ?? 0 }))) };
 }

package/src/runtime/pose.ts

@@ -1,5 +1,5 @@
 /**
- * The runtime poser's per-instance half (issue #1591, stage 0): one
+ * The runtime poser's per-instance half (issue #1591, stage 1): one
  * `RuntimePose` per skeleton on screen, every buffer allocated when it is
  * made and overwritten in place on every pose, so that posing a frame
  * allocates nothing.
@@ -71,6 +71,7 @@ import {
   W_Y,
   WORLDS,
   type RuntimeAnimation,
+  type RuntimeEvent,
   type RuntimeIk,
   type RuntimeModel,
   type RuntimeTransform,
@@ -114,6 +115,11 @@ export class RuntimePose {
   trackTime = 0;
   time = 0;
 
+  private readonly fired: RuntimeEvent[] = [];
+  /** Borrowed immutable event records, in delivery order, until the next apply/step. */
+  get events(): readonly RuntimeEvent[] { return this.fired; }
+  private eventTime = -1;
+
   private current: RuntimeAnimation | null = null;
   private readonly cursors: Int32Array;
   // The constraints' values as posed: an ik's mix, softness and flags, a transform's six mixes.
@@ -160,12 +166,30 @@ export class RuntimePose {
     this.cursors.fill(-1);
     this.trackTime = 0;
     this.time = 0;
+    this.eventTime = -1;
+    this.fired.length = 0;
+  }
+
+  /**
+   * Restore one animation's two clocks without delivering keys already passed.
+   * A skin/view replacement uses the old pose's trackTime and wrapped time.
+   * Unlike setAnimation + apply, restoration never replays the initial interval.
+   */
+  restore(name: string, trackTime: number, animationTime: number): void {
+    if (!Number.isFinite(trackTime)) throw new RuntimeInputError(`restore: track time ${trackTime} is not finite`);
+    if (!Number.isFinite(animationTime)) throw new RuntimeInputError(`restore: animation time ${animationTime} is not finite`);
+    this.setAnimation(name);
+    this.trackTime = trackTime;
+    if (!this.model.restoreEventsFromStart) this.eventTime = animationTime;
+    this.apply(animationTime);
   }
 
   /** The setup pose: every constraint applied with its own values, every slot as it is set up. */
   setupPose(): void {
     this.current = null;
     this.time = 0;
+    this.eventTime = -1;
+    this.fired.length = 0;
     this.locals.set(this.model.setup);
     this.hierarchy();
     this.constraintValues(null, 0);
@@ -178,6 +202,7 @@ export class RuntimePose {
     const anim = this.current;
     if (anim === null) throw new RuntimeInputError('apply: no animation is set (setAnimation first)');
     if (!Number.isFinite(t)) throw new RuntimeInputError(`apply: the time ${t} is not finite`);
+    this.collectEvents(anim, t);
     this.time = t;
     this.boneTimelines(anim, t);
     this.hierarchy();
@@ -194,6 +219,21 @@ export class RuntimePose {
     this.apply(anim.duration === 0 ? 0 : this.trackTime % anim.duration);
   }
 
+  /** The oracle interval (last,t], tail then head on a wrap; never copies a payload. */
+  private collectEvents(anim: RuntimeAnimation, t: number): void {
+    const last = this.eventTime;
+    const wrapped = t < last;
+    const keys = anim.eventKeys;
+    let count = 0;
+    if (wrapped) for (let i = 0; i < keys.length; i++) if (keys[i].time > last) this.fired[count++] = keys[i];
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i];
+      if (key.time <= t && (wrapped ? !this.model.eventWrapOffByOne || key.time > 0 : key.time > last)) this.fired[count++] = key;
+    }
+    this.fired.length = count;
+    this.eventTime = t;
+  }
+
   // ---------------------------------------------------------------------------
   // the bones
   // ---------------------------------------------------------------------------