@rig-c/core 2.72.0 → 2.74.0

package/README.md

@@ -51,6 +51,16 @@ Everything in that table needs Bun and this package — `preview` and `vote` als
 `@esotericsoftware/spine-core` installed beside it (see below) — and no clone, no
 reference art, no art pipeline, no server.
 
+### Alpha-derived clipping
+
+Alpha-derived clipping takes a named source slot/skin/attachment plus explicit
+alpha threshold, drawing-pixel simplification tolerance and mapped vertex budget.
+Region, authored/resolved linked mesh and generated grid/contour depth sources use
+ordinary weighted clipping, with the existing validation gate before emission.
+See [AUTHORING: Alpha-derived clipping](docs/AUTHORING.md#alpha-derived-clipping)
+for source-motion limits, fit reports and named refusals, and
+[the face guide](docs/FACE.md#a-measured-alpha-aperture) for the depth-yaw flow.
+
 ## What rigc is, and what it is not
 
 rigc emits **Spine's own skeleton data format**. That is the whole positioning, and

package/docs/AUTHORING.md

@@ -2620,6 +2620,7 @@ attachment rather than a second set of art.
 | --- | --- |
 | `type` | `"clipping"`. **Required** |
 | `name`, `vertexCount`, `vertices`, `weights`, `boneIndexing`, `color` | exactly as on a bounding box |
+| `alphaClip` | Optional generated clipping geometry from a named source plate. Declare `skin`, `slot`, `attachment`, `alpha`, `tolerance`, and `maxVertices` in the object; all six are required. This form excludes authored vertex geometry and `convex`/`inverse`. See **Alpha-derived clipping** for source, carrier, budget, and deform refusals. |
 | `end` | the last slot the clip applies to, **by name**. Absent is the parser's own encoding for *clip everything after this one*, which is why a typo cannot be told from an omission once the file is loaded: `findSlot` returns null on a miss and the parser assigns that null without a word, so the clip 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 — `end names slot "X", which this rig does not declare` — and `A33` refuses it again on a skeleton rigc did not write |
 | `convex` | default **false**. True tells the runtime the polygon is convex so it can clip without triangulating it, and a polygon that deforms concave is clipped by its convex hull instead (`ClippingAttachment.convex`). Nothing here checks that the polygon is in fact convex |
 | `inverse` | default **false**. True makes everything **outside** the polygon visible instead of everything inside, and inverse clipping is always treated as convex (`ClippingAttachment.inverse`) |
@@ -7781,7 +7782,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; 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”.<br>Exact fixed diagnostic chunks (named values between chunks vary): ⟦ alphaClip⟧<br>⟦alphaClip⟧ | 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. |
@@ -12523,7 +12524,93 @@ 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 1)
+### Alpha-derived clipping
+
+A clipping attachment may replace authored `vertexCount`/`vertices`/`weights` with
+`alphaClip`. The two forms are exclusive. This creates ordinary weighted clipping
+geometry; it introduces no runtime alpha mask or new projection model.
+
+```json
+{"type":"clipping","end":"content","alphaClip":{
+  "skin":"default","slot":"aperture","attachment":"aperture",
+  "alpha":128,"tolerance":0.5,"maxVertices":256
+}}
+```
+
+All six fields are required. `skin`, `slot`, `attachment` name the source's exact
+placeholder identity, independent of draw order; no current-skin/setup-attachment
+guess is made. `alpha` is an integer in 1..255, `tolerance` is a positive distance
+in the drawing's pixels, and `maxVertices` is an integer >=3. These example values
+are declarations, not defaults. The measured alpha is the decoded source plate,
+not the source slot's animated opacity. A hidden source slot may supply the plate.
+
+Sources are regions, meshes (generated grid/contour included), or linked meshes
+whose ordinary source resolution succeeded. Atlas rotation/trim extraction and
+**declared** scale apply before tracing. The source must have one nonempty island,
+transparent exterior and no holes; a single clipping polygon cannot encode holes.
+A sequence has no single immutable plate and is refused. Missing or ambiguous UV
+carriers refuse the build instead of extrapolating the source surface.
+
+The simplified outline is split at every source UV-triangle crossing. Every
+partitioned open interval also requires a unique carrier: carried endpoints alone
+cannot authorize a straight bridge across a hole in the source UV domain. UV
+barycentrics locate the source's setup position, per-bone weighted first moments
+and sampled depth. Those crossings count against `maxVertices`. The resulting
+named weighted bindings follow the source bones even if the clip slot belongs to
+a different bone. They do **not** inherit another attachment's deform timeline.
+For a source that deforms, explicitly give source and clip identical affine or
+`depth:true` yaw/pitch transform keys in compatible source/clip `DeformGeometry`
+frames. Existing
+`compileDeformTrack` evaluates both; clip depth comes from interpolation of the
+source's sampled vertex depths, not a second sample of a nonlinear depth image.
+The frame is derived by `deformGeometryOf`: a bind-space frame requires exactly
+one influence per vertex and exactly one bone; duplicate influences on that same
+bone instead evaluate in world space. A world-source/bind-clip mismatch is refused
+by name. Compatible world/world affine or depth transforms are accepted when
+source influence shares are constant across vertices, so interpolation commutes
+with both projection and moving bone matrices. Dense keys, envelopes/nonlinear
+transforms and varying world-space shares cannot silently leave a clip static;
+they receive a named representability refusal. Static multi-bone sources
+use their existing named weighted geometry without a new solver.
+
+`build` on both entries and `explain` print a `CLIP` row: source/target identity,
+threshold/tolerance, traced/simplified/emitted vertex counts and budget,
+`coveredArt/artPixels`, coverage, false-positive/negative **pixel-centre cells**,
+maximum original trace-corner distance to the simplified outline, overshoot, and
+`maxBindingDeviation` (maximum world-space discrepancy from source-carrier setup
+positions after final float32 binding/world rounding).
+Trace/overshoot distances are drawing pixels, including on a scaled atlas;
+binding deviation explicitly uses world units. Final float32 adjacent duplicate,
+foldback and zero-area polygons are refused, not silently pruned. This is a threshold
+silhouette fit, not soft-alpha pixel equality. Coverage/distance scalars display
+six decimal places (display rounding envelope 0.5e-6); counts are exact. Do not
+compare the shortened display against exact float32 equality. No mesh-specific
+99.5% coverage cutoff or offset margin is applied to a clipping boundary.
+
+The ordinary validation gate still precedes artifact writes. `A18` compares
+independent emits and `A33` reads clipping geometry; neither alone proves the
+posed mask is the intended aperture. The controlled proof separately compares
+the threshold plate on the actual posed source surface, clip boundary and both
+renderers at four gaze directions × depth yaw ±15°. It fixes viewport/background,
+uses output pixel centres and the existing premultiplied bilinear reader, and
+separates soft-edge quantization from simplification/projection/filtering error.
+A real licensed editor import/export and nonempty per-state pixel/binding checks
+remain separate requirements; editor harness exit 0 or parser tests are not a
+verdict on those figures.
+
+| Code | Named refusal and repair |
+| --- | --- |
+| <a id="CE_COMPILE_ALPHA_CLIP_PARAMETERS"></a>`CE_COMPILE_ALPHA_CLIP_PARAMETERS` | Alpha/tolerance/scale/budget names its actual value and required range. Declare every parameter; never choose a threshold by eye during a run.<br>Exact fixed diagnostic chunks (named values between chunks vary): ⟦: alphaClip.alpha is ⟧<br>⟦; required an integer in 1..255. Declare the threshold.⟧<br>⟦: alphaClip.tolerance=⟧<br>⟦, page scale=⟧<br>⟦required finite positive drawing-pixel tolerance and page scale.⟧<br>⟦: alphaClip.maxVertices is ⟧<br>⟦; required an integer &gt;=3. ⟧<br>⟦Declare the complete mapped polygon budget.⟧ |
+| <a id="CE_COMPILE_ALPHA_CLIP_NO_ALPHA"></a>`CE_COMPILE_ALPHA_CLIP_NO_ALPHA` | `slotwithnoalpha`: the actual pixel count above threshold is zero or the whole window. Supply a nonempty silhouette with transparent exterior. An opaque RGBA channel is not a silhouette.<br>Exact fixed diagnostic chunks (named values between chunks vary): ⟦: slotwithnoalpha: ⟧<br>⟦ of ⟧<br>⟦ pixels reach alpha ⟧<br>⟦; ⟧<br>⟦required a nonempty silhouette with transparent exterior. Supply alpha art or declare a threshold that measures a silhouette.⟧ |
+| <a id="CE_COMPILE_ALPHA_CLIP_TOPOLOGY"></a>`CE_COMPILE_ALPHA_CLIP_TOPOLOGY` | Trace cannot form one simple outline, has holes/islands/pinches, or simplifies below three vertices. Repair the source or lower the declared tolerance; holes are never silently filled.<br>Exact fixed diagnostic chunks (named values between chunks vary): ⟦: clipping has ⟧<br>⟦ vertices; required &gt;=3 after final coordinate rounding.⟧<br>⟦: adjacent clipping vertices ⟧<br>⟦ and ⟧<br>⟦[⟧<br>⟦] and [⟧<br>⟦]; required finite distinct neighbours after final coordinate rounding. ⟧<br>⟦Lower the source coordinate magnitude or simplify the outline.⟧<br>⟦: adjacent edges ⟧<br>⟦ fold back after rounding; ⟧<br>⟦required a nondegenerate simple clipping boundary.⟧<br>⟦: clipping doubled area is ⟧<br>⟦ after coordinate rounding; required nonzero area.⟧<br>⟦: alpha outline cannot be represented: ⟧<br>⟦bad part size ⟧<br>⟦x⟧<br>⟦the alpha mask holds ⟧<br>⟦ bytes for a ⟧<br>⟦ part⟧<br>⟦no pixel of the ⟧<br>⟦ part reaches alpha ⟧<br>⟦; there is no silhouette to trace⟧<br>⟦the alpha silhouette pinches to a single point at pixel corner (⟧<br>⟦), where two parts of the art ⟧<br>⟦meet diagonally — one outline cannot pass through one point twice. Move the alpha threshold so the ⟧<br>⟦pinch opens (raise it) or closes (lower it), or author the geometry as weights⟧<br>⟦the alpha trace did not close; the mask is not a closed region⟧<br>⟦the alpha trace reached a dead end at corner (⟧<br>⟦); the mask is not a closed region⟧<br>⟦; required one simple connected outline.⟧<br>⟦: alpha ⟧<br>⟦ islands and ⟧<br>⟦ hole pixels; ⟧<br>⟦required one island without holes. Separate the source or author clipping geometry.⟧ |
+| <a id="CE_COMPILE_ALPHA_CLIP_SELF_INTERSECTION"></a>`CE_COMPILE_ALPHA_CLIP_SELF_INTERSECTION` | `selfintersectionaftersimplification`: names intersecting edges. Lower tolerance or repair the source topology. The forged-crossing helper control is not evidence of a traced raster counterexample.<br>Exact fixed diagnostic chunks (named values between chunks vary): ⟦: selfintersectionaftersimplification: edges ⟧<br>⟦ and ⟧<br>⟦intersect; required one simple outline. Lower tolerance or repair the source topology.⟧ |
+| <a id="CE_COMPILE_ALPHA_CLIP_CARRIER"></a>`CE_COMPILE_ALPHA_CLIP_CARRIER` | Source UV carrier missing/ambiguous at the named outline vertex or partitioned open interval. Extend coverage or repair overlapping source triangles; no extrapolation.<br>Exact fixed diagnostic chunks (named values between chunks vary): ⟦: source UV carrier is ambiguous: ⟧<br>⟦COMPARE_UV_CARRIER_NOT_UNIQUE⟧<br>⟦required unique source geometry. Repair overlapping UV triangles.⟧<br>⟦: source has no UV carrier for outline vertex ⟧<br>⟦ at [⟧<br>⟦]; ⟧<br>⟦required coverage of the complete clipping outline. Extend the source geometry or lower tolerance.⟧<br>⟦: outline interval ⟧<br>⟦ from [⟧<br>⟦] to [⟧<br>⟦] ⟧<br>⟦has no source UV carrier at open midpoint [⟧<br>⟦]; required complete interval coverage. ⟧<br>⟦Fill the source UV gap; carried endpoints cannot authorize a bridge.⟧ |
+| <a id="CE_COMPILE_ALPHA_CLIP_VERTEX_BUDGET"></a>`CE_COMPILE_ALPHA_CLIP_VERTEX_BUDGET` | `polygonoverdeclaredvertexbudget`: actual mapped count exceeds declared limit, including source-triangle crossings. Raise the budget or simplify the outline/source.<br>Exact fixed diagnostic chunks (named values between chunks vary): ⟦ alphaClip from "⟧<br>⟦"⟧<br>⟦: polygonoverdeclaredvertexbudget: ⟧<br>⟦ vertices after source carrier crossings (⟧<br>⟦ simplified), required &lt;=⟧<br>⟦. Raise the declared budget or simplify the source/outline.⟧ |
+| <a id="CE_COMPILE_ALPHA_CLIP_SOURCE"></a>`CE_COMPILE_ALPHA_CLIP_SOURCE` | Names missing identity/plate, wrong source kind, sequence or unlocated atlas grid. Supply exact source identity and static plate geometry. A clipping source cannot serve as its own dependency.<br>Exact fixed diagnostic chunks (named values between chunks vary): ⟦: generated clipping target was not filed in its skin; required a resolved attachment.⟧<br>⟦: alphaClip.⟧<br>⟦ is ⟧<br>⟦; required an explicit nonempty source name.⟧<br>⟦ alphaClip from "⟧<br>⟦"⟧<br>⟦: source attachment is absent; required a declared slot/skin/attachment.⟧<br>⟦: source kind is ⟧<br>⟦; required a region or resolved mesh with pixels.⟧<br>⟦: linked source resolves to ⟧<br>⟦nothing⟧<br>⟦; required a resolved mesh.⟧<br>⟦: source is ⟧<br>⟦; required region or mesh geometry with a plate (a clipping source would be a dependency cycle).⟧<br>⟦: source has a ⟧<br>⟦-frame sequence; required one immutable source plate. Select a separate named attachment for the measured frame.⟧<br>⟦: region "⟧<br>⟦" has no source plate; required image/atlas pixels.⟧<br>⟦: source plate grid cannot be located. ⟧<br>⟦page "⟧<br>⟦" declares ⟧<br>⟦ and its PNG is ⟧<br>⟦ — ⟧<br>⟦ of the declared width and ⟧<br>⟦ of the declared height⟧<br>⟦A runtime does not read the file's own size anywhere in the region mapping — &#96;TextureAtlas&#96; computes every ⟧<br>⟦region's UVs as a fraction of the DECLARED size (&#96;region.u = region.x / page.width&#96;, spine-core ⟧<br>⟦&#96;dist/TextureAtlas.js:162-171&#96;) — so a page whose PNG is the declared page RESCALED draws the same picture at ⟧<br>⟦the file's resolution, and one whose PNG is anything else draws whatever sits at those fractions. What a ⟧<br>⟦declared size that disagrees with the file breaks is every reader that addresses the page in TEXELS: this ⟧<br>⟦validator's own &#96;A19&#96; alpha scan, the region lift rigc's mesh generators trace, and a canvas renderer that ⟧<br>⟦cuts each part out of the page by source rectangle.⟧<br>⟦The &#96;scale:&#96; header states one ratio for both axes, so a page whose axes differ cannot be ⟧<br>⟦declared honestly at all: re-export the page at ⟧<br>⟦, or repack it.⟧<br>⟦The format states coarser texels with the &#96;scale:&#96; header, but this page cannot be re-declared ⟧<br>⟦that way: ⟧<br>⟦region ⟧<br>⟦'s &#96;⟧<br>⟦&#96; of ⟧<br>⟦ becomes ⟧<br>⟦ on the file's own grid, which is not a whole texel⟧<br>⟦. Re-export the page at ⟧<br>⟦The format states coarser texels with the &#96;scale:&#96; header and rigc builds that: declare ⟧<br>⟦&#96;size: ⟧<br>⟦&#96; with &#96;scale: ⟧<br>⟦&#96; and multiply every ⟧<br>⟦&#96;bounds&#96;/&#96;offsets&#96; on this page by ⟧<br>⟦, and every part keeps the size it ⟧<br>⟦has now.⟧ |
+| <a id="CE_COMPILE_ALPHA_CLIP_CONFLICT"></a>`CE_COMPILE_ALPHA_CLIP_CONFLICT` | Names authored fields or convex/inverse flags conflicting with generated inside-clipping geometry. Use one authored/generated form.<br>Exact fixed diagnostic chunks (named values between chunks vary): ⟦: alphaClip conflicts with [⟧<br>⟦vertexCount⟧<br>⟦vertices⟧<br>⟦weights⟧<br>⟦boneIndexing⟧<br>⟦, ⟧<br>⟦], convex=⟧<br>⟦, inverse=⟧<br>⟦; required ordinary inside clipping with generated geometry only. Remove authored geometry/flags.⟧ |
+| <a id="CE_COMPILE_ALPHA_CLIP_DEFORM"></a>`CE_COMPILE_ALPHA_CLIP_DEFORM` | Names animation and source/clip key/frame counts that cannot share the existing projection contract. Give matching explicit supported transform keys in compatible actual frames, with constant world shares where needed, or author the corresponding clip geometry and motion; weighted binding does not copy source deform.<br>Exact fixed diagnostic chunks (named values between chunks vary): ⟦ alphaClip from "⟧<br>⟦"⟧<br>⟦: animation "⟧<br>⟦" has ⟧<br>⟦ source and ⟧<br>⟦ clip keys; source frame=⟧<br>⟦no vertex geometry⟧<br>⟦clip frame=⟧<br>⟦, constant world influence shares=⟧<br>⟦Required matching explicit affine/depth-yaw/pitch transforms in compatible DeformGeometry frames, ⟧<br>⟦with constant shares for world-space transfer. Fix the named frame/keys or author corresponding clip motion.⟧ |
+
+## 15. Posing in place for a player — the runtime poser (stage 2)
 
 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,
@@ -12558,15 +12645,28 @@ 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 1 poses |
+| | what stage 2 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 |
+| deform | weighted and unweighted mesh timelines, linear/stepped/Bézier, per-pose key cursors and in-place buffers; linked meshes inherit their source's timelines only with `timelines: true` |
 | 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) |
 
+Deform keys are expanded once at load. Unweighted keys hold float32 positions,
+`fround(fround(setup) + fround(offset))`; weighted keys hold float32 offsets,
+**one x/y pair per influence**, in vertex then influence order. At a pose,
+interpolation stays double. Each weighted offset is added to its float32 binding
+coordinate before the bone transform, translation and weight, summed in binding
+order. Bézier uses the oracle's deform recurrence end `0.99999999` and its
+product-before-division first and last pieces, rather than ordinary channel easing.
+Attachment switches resolve before deform matching by source skin/slot/placeholder;
+display names do not identify timelines. Every pose clears deform state, including
+before the first key, at setup, on backwards seeks and across loop wraps. Buffers
+and cursors belong to the pose; compiling another skin resolves another identity.
+
 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
@@ -12594,7 +12694,7 @@ 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 1), N construct(s) missing:
+reads `not posed by the runtime poser (stage 2), 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
@@ -12610,7 +12710,7 @@ refused: nothing is posed approximately.
 | `clipping`, `null-atlas-region` | the model when shown at setup, else the animation that keys it | a clipping attachment; a region whose atlas rectangle the model states as `null` |
 | `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`) |
+| `inherit-timeline`, `sequence-timeline`, `draw-order-timeline`, `dark-colour-timeline` | the animation | a timeline of that kind (`dark-colour` is `rgba2` / `rgb2`) |
 
 A call it cannot answer throws `RuntimeInputError`, naming the call:
 `apply: no animation is set (setAnimation first)`, `animation "x" is not one of
@@ -12630,7 +12730,7 @@ the poses and values compared. A `DIFF` or `REFUSED` turns the run RED; a SKIP
 never counts as a pass. The page UVs are the atlas's and are compared by neither
 side here. The selftest's `runtime-poser` suite holds the gate to its plants (a
 1e-6° bone perturbation, a weighted binding bound to the wrong bone index, a
-refused feature smuggled through — each caught by name), a seeded population of
+omitted deform — 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.
 

package/docs/FACE.md

@@ -1946,3 +1946,22 @@ a different document and a different measurement. Everything here is one head
 turning, blinking and looking — and the one general lesson that might carry into
 that work is §7's: **allocate the channels before the first key, because Spine
 blends and does not add.**
+
+### A measured alpha aperture
+
+A named socket plate can supply an `alphaClip` clipping attachment (AUTHORING,
+**Alpha-derived clipping**). This also accepts a generated grid/contour source
+with a depth sheet: the clip is carried by the source's UV/setup bindings and
+sampled depths, independent of the clip slot's own bone. Give source and clip
+explicit matching existing depth-yaw transform keys; a weight does not inherit
+another attachment's deformation. Source-triangle crossings become clip vertices
+and count against the declared budget. Do not replace this turn with a cosine-only
+stand-in, fill a source hole, or infer threshold/tolerance from an appearance.
+
+`tools/alpha_clip_proof.ts --out <evidence>` builds a controlled painted ellipse
+and measures four gazes at yaw ±15°, with separate threshold/soft-edge error and
+source-boundary checks beside core/SkeletonClipping pixel parity. Fixed framing
+prevents a shifted clip from being hidden by automatic crop changes. These are
+controlled CPU-render/geometry observations when actually run; they do not certify
+production art, editor operation or browser/GPU playback. The actual editor trip
+must preserve the clip's end, bindings and nonempty per-state render figures too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.72.0",
+  "version": "2.74.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/alpha_clip.ts

@@ -0,0 +1,255 @@
+/** Alpha-outline geometry and UV carriers, independent of emitters and posers. */
+import { CompileError } from './errors.ts';
+import {
+  earClip, findSelfIntersection, traceAlphaOutline, simplifyClosedPolygon,
+  measureAuthoredMeshFit, rasteriseTriangles, MeshError, type AlphaMask,
+} from './mesh.ts';
+import { uvCarriers, CONTAINS, type Carrier } from './meshcarriers.ts';
+import { hypot2 } from './numeric.ts';
+import type { RigAlphaClip } from './rig.ts';
+import type { AlphaClipReport } from './types.ts';
+
+export type ClipPoint = [number, number];
+const cross = (a: ClipPoint, b: ClipPoint): number => a[0] * b[1] - a[1] * b[0];
+const sub = (a: ClipPoint, b: ClipPoint): ClipPoint => [a[0] - b[0], a[1] - b[1]];
+
+export function clipDistance(p: readonly number[], a: readonly number[], b: readonly number[]): number {
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  const length2 = dx * dx + dy * dy;
+  const projection = ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / (length2 || 1);
+  const t = Math.max(0, Math.min(1, projection));
+  return hypot2(p[0] - a[0] - t * dx, p[1] - a[1] - t * dy);
+}
+
+/** Neighbour degeneracies are not covered by the nonadjacent intersection check. */
+export function refuseClipDegeneracy(points: ClipPoint[], where: string): void {
+  if (points.length < 3) {
+    throw new CompileError(
+      `${where}: clipping has ${points.length} vertices; required >=3 after final coordinate rounding.`,
+      'CE_COMPILE_ALPHA_CLIP_TOPOLOGY',
+    );
+  }
+  let area2 = 0;
+  for (let i = 0; i < points.length; i++) {
+    const a = points[i];
+    const b = points[(i + 1) % points.length];
+    const c = points[(i + 2) % points.length];
+    if (!a.every(Number.isFinite) || (a[0] === b[0] && a[1] === b[1])) {
+      throw new CompileError(
+        `${where}: adjacent clipping vertices ${i} and ${(i + 1) % points.length} are ` +
+          `[${a}] and [${b}]; required finite distinct neighbours after final coordinate rounding. ` +
+          'Lower the source coordinate magnitude or simplify the outline.',
+        'CE_COMPILE_ALPHA_CLIP_TOPOLOGY',
+      );
+    }
+    const incoming = sub(b, a);
+    const outgoing = sub(c, b);
+    if (cross(incoming, outgoing) === 0 && incoming[0] * outgoing[0] + incoming[1] * outgoing[1] < 0) {
+      throw new CompileError(
+        `${where}: adjacent edges ${i} and ${(i + 1) % points.length} fold back after rounding; ` +
+          'required a nondegenerate simple clipping boundary.',
+        'CE_COMPILE_ALPHA_CLIP_TOPOLOGY',
+      );
+    }
+    area2 += cross(a, b);
+  }
+  if (area2 === 0) {
+    throw new CompileError(
+      `${where}: clipping doubled area is ${area2} after coordinate rounding; required nonzero area.`,
+      'CE_COMPILE_ALPHA_CLIP_TOPOLOGY',
+    );
+  }
+}
+
+/** Check simplifier output and mapped source-triangle crossings before emission. */
+export function refuseClipCrossing(points: ClipPoint[], where: string): void {
+  const crossing = findSelfIntersection(points);
+  if (crossing) {
+    throw new CompileError(
+      `${where}: selfintersectionaftersimplification: edges ${crossing[0]} and ${crossing[1]} ` +
+        'intersect; required one simple outline. Lower tolerance or repair the source topology.',
+      'CE_COMPILE_ALPHA_CLIP_SELF_INTERSECTION',
+    );
+  }
+}
+
+type OutlineReport = Omit<AlphaClipReport, 'target' | 'source' | 'vertices' | 'uvs' | 'maxBindingDeviationWorld'>;
+
+export function alphaClipOutline(
+  mask: AlphaMask,
+  spec: RigAlphaClip,
+  where: string,
+  pageScale = 1,
+): { points: ClipPoint[]; report: OutlineReport } {
+  if (!Number.isInteger(spec.alpha) || spec.alpha < 1 || spec.alpha > 255) {
+    throw new CompileError(
+      `${where}: alphaClip.alpha is ${String(spec.alpha)}; required an integer in 1..255. Declare the threshold.`,
+      'CE_COMPILE_ALPHA_CLIP_PARAMETERS',
+    );
+  }
+  if (!Number.isFinite(spec.tolerance) || spec.tolerance <= 0 || !Number.isFinite(pageScale) || pageScale <= 0) {
+    throw new CompileError(
+      `${where}: alphaClip.tolerance=${String(spec.tolerance)}, page scale=${pageScale}; ` +
+        'required finite positive drawing-pixel tolerance and page scale.',
+      'CE_COMPILE_ALPHA_CLIP_PARAMETERS',
+    );
+  }
+  if (!Number.isInteger(spec.maxVertices) || spec.maxVertices < 3) {
+    throw new CompileError(
+      `${where}: alphaClip.maxVertices is ${String(spec.maxVertices)}; required an integer >=3. ` +
+        'Declare the complete mapped polygon budget.',
+      'CE_COMPILE_ALPHA_CLIP_PARAMETERS',
+    );
+  }
+  let below = 0;
+  let above = 0;
+  for (const alpha of mask.alpha) {
+    if (alpha < spec.alpha) below++;
+    else above++;
+  }
+  if (above === 0 || below === 0) {
+    throw new CompileError(
+      `${where}: slotwithnoalpha: ${above} of ${mask.width * mask.height} pixels reach alpha ${spec.alpha}; ` +
+        'required a nonempty silhouette with transparent exterior. Supply alpha art or declare a threshold that measures a silhouette.',
+      'CE_COMPILE_ALPHA_CLIP_NO_ALPHA',
+    );
+  }
+  let traced: ReturnType<typeof traceAlphaOutline>;
+  try {
+    traced = traceAlphaOutline(mask, spec.alpha);
+  } catch (error) {
+    if (!(error instanceof MeshError)) throw error;
+    throw new CompileError(
+      `${where}: alpha outline cannot be represented: ${error.message}; required one simple connected outline.`,
+      'CE_COMPILE_ALPHA_CLIP_TOPOLOGY',
+    );
+  }
+  if (traced.islands !== 1 || traced.holePixels !== 0) {
+    throw new CompileError(
+      `${where}: alpha ${spec.alpha} has ${traced.islands} islands and ${traced.holePixels} hole pixels; ` +
+        'required one island without holes. Separate the source or author clipping geometry.',
+      'CE_COMPILE_ALPHA_CLIP_TOPOLOGY',
+    );
+  }
+  const points = simplifyClosedPolygon(traced.outline, spec.tolerance * pageScale);
+  refuseClipCrossing(points, where);
+  refuseClipDegeneracy(points, where);
+  const triangles = clipTrianglesOf(points);
+  const fit = measureAuthoredMeshFit(mask, spec.alpha, points, triangles);
+  let maxTraceDeviation = 0;
+  for (const point of traced.outline) {
+    const distance = Math.min(...points.map((a, i) => clipDistance(point, a, points[(i + 1) % points.length])));
+    maxTraceDeviation = Math.max(maxTraceDeviation, distance);
+  }
+  const filled = rasteriseTriangles(points, triangles, mask.width, mask.height).reduce((sum, bit) => sum + bit, 0);
+  return {
+    points,
+    report: {
+      alpha: spec.alpha,
+      tolerance: spec.tolerance,
+      maxVertices: spec.maxVertices,
+      tracedVertices: traced.outline.length,
+      simplifiedVertices: points.length,
+      artPixels: fit.artPixels,
+      coveredArt: fit.coveredArt,
+      coverage: fit.coverage,
+      falsePositive: filled - fit.coveredArt,
+      falseNegative: fit.artPixels - fit.coveredArt,
+      maxTraceDeviation: maxTraceDeviation / pageScale,
+      overshoot: fit.overshoot / pageScale,
+    },
+  };
+}
+
+export function clipTrianglesOf(points: ClipPoint[]): number[] {
+  return earClip(points);
+}
+
+/** Offline cell/reference reading, not a runtime alpha-mask feature. */
+export function clipContains(points: readonly (readonly number[])[], x: number, y: number): boolean {
+  let inside = false;
+  for (let i = 0, j = points.length - 1; i < points.length; j = i++) {
+    const a = points[i];
+    const b = points[j];
+    if ((a[1] > y) !== (b[1] > y) && x < (b[0] - a[0]) * (y - a[1]) / (b[1] - a[1]) + a[0]) inside = !inside;
+  }
+  return inside;
+}
+
+function carriersOf(
+  points: ClipPoint[], uvs: readonly number[], triangles: readonly number[], where: string,
+): Array<Carrier | null> {
+  try {
+    return uvCarriers(uvs, triangles, points.map((uv) => ({ uv })), where);
+  } catch (error) {
+    throw new CompileError(
+      `${where}: source UV carrier is ambiguous: ${error instanceof Error ? error.message : String(error)}; ` +
+        'required unique source geometry. Repair overlapping UV triangles.',
+      'CE_COMPILE_ALPHA_CLIP_CARRIER',
+    );
+  }
+}
+
+/** Split BEFORE mapping: an edge across source triangles is piecewise affine, not one chord. */
+export function clipCarriers(
+  ring: ClipPoint[], uvs: readonly number[], triangles: readonly number[], where: string,
+): { points: ClipPoint[]; carriers: Carrier[] } {
+  const edges = new Map<string, [number, number]>();
+  for (let i = 0; i < triangles.length; i += 3) {
+    const triplet = triangles.slice(i, i + 3);
+    for (const [a, b] of [[triplet[0], triplet[1]], [triplet[1], triplet[2]], [triplet[2], triplet[0]]]) {
+      edges.set(`${Math.min(a, b)}/${Math.max(a, b)}`, [a, b]);
+    }
+  }
+  const points: ClipPoint[] = [];
+  for (let i = 0; i < ring.length; i++) {
+    const a = ring[i];
+    const b = ring[(i + 1) % ring.length];
+    const direction = sub(b, a);
+    const cuts = [0];
+    for (const [v, w] of edges.values()) {
+      const c: ClipPoint = [uvs[2 * v], uvs[2 * v + 1]];
+      const e: ClipPoint = [uvs[2 * w], uvs[2 * w + 1]];
+      const edge = sub(e, c);
+      const denominator = cross(direction, edge);
+      if (denominator === 0) continue;
+      const t = cross(sub(c, a), edge) / denominator;
+      const u = cross(sub(c, a), direction) / denominator;
+      if (t > CONTAINS && t < 1 - CONTAINS && u >= -CONTAINS && u <= 1 + CONTAINS) cuts.push(t);
+    }
+    cuts.sort((x, y) => x - y);
+    for (let k = 0; k < cuts.length; k++) {
+      if (k === 0 || cuts[k] - cuts[k - 1] > CONTAINS) {
+        points.push([a[0] + cuts[k] * direction[0], a[1] + cuts[k] * direction[1]]);
+      }
+    }
+  }
+  const carriers = carriersOf(points, uvs, triangles, where);
+  const missing = carriers.findIndex((carrier) => carrier === null);
+  if (missing >= 0) {
+    throw new CompileError(
+      `${where}: source has no UV carrier for outline vertex ${missing} at [${points[missing]}]; ` +
+        'required coverage of the complete clipping outline. Extend the source geometry or lower tolerance.',
+      'CE_COMPILE_ALPHA_CLIP_CARRIER',
+    );
+  }
+  // Endpoints can all be carried while an edge bridges a missing strip. Since all
+  // triangle-edge crossings partition the ring, a unique open midpoint identifies
+  // the actual affine source map throughout that entire open segment.
+  const midpoints = points.map((a, i): ClipPoint => {
+    const b = points[(i + 1) % points.length];
+    return [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2];
+  });
+  const intervals = carriersOf(midpoints, uvs, triangles, `${where} open outline intervals`);
+  const gap = intervals.findIndex((carrier) => carrier === null);
+  if (gap >= 0) {
+    throw new CompileError(
+      `${where}: outline interval ${gap} from [${points[gap]}] to [${points[(gap + 1) % points.length]}] ` +
+        `has no source UV carrier at open midpoint [${midpoints[gap]}]; required complete interval coverage. ` +
+        'Fill the source UV gap; carried endpoints cannot authorize a bridge.',
+      'CE_COMPILE_ALPHA_CLIP_CARRIER',
+    );
+  }
+  return { points, carriers: carriers as Carrier[] };
+}

package/src/cli/core_commands.ts

@@ -50,7 +50,7 @@ import { attachmentRegionJoins } from '../region_joins.ts';
 import { cmdRepack } from './repack.ts';
 import { writeWhole } from './write_whole.ts';
 import { GUIDE_FILE, GUIDE_RULE_TABLES_ELSEWHERE, guideAnswer, refusalLine } from '../guide.ts';
-import { ATLAS_ABSENT, COMMANDS, type CommandRun, DelegateError, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, GuideError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPageEdges, readPoserFlag, readSheetFormat, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson, documentStageBeside } from './shared.ts';
+import { ATLAS_ABSENT, COMMANDS, type CommandRun, DelegateError, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, GuideError, printAlphaClips, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPageEdges, readPoserFlag, readSheetFormat, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson, documentStageBeside } from './shared.ts';
 import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
@@ -1886,6 +1886,7 @@ export function cmdExplain(flags: Record<string, string>): void {
     }
   }
 
+  printAlphaClips(result);
   if (result.meshes.length) {
     console.log('\nmeshes');
     for (const kind of new Set(result.meshes.map((m) => m.kind))) console.log(`  ${MESH_KIND_NOTES[kind]}`);

package/src/cli/shared.ts

@@ -2400,6 +2400,18 @@ export function readBuildInvocation(flags: Record<string, string>): { label: str
   return { label, opts, profile, packing };
 }
 
+/** Six decimal places: display error <=0.5e-6 per scalar; cells/counts remain integers. */
+export function printAlphaClips(result: Pick<CompileResult, 'alphaClips'>): void {
+  for (const clip of result.alphaClips ?? []) console.log(
+    `  CLIP  ${clip.target} from=${clip.source} alpha=${clip.alpha} tolerance=${clip.tolerance} drawing-px ` +
+    `vertices=${clip.vertices}/${clip.maxVertices} traced=${clip.tracedVertices} simplified=${clip.simplifiedVertices} ` +
+    `coverage=${clip.coverage.toFixed(6)} (${clip.coveredArt}/${clip.artPixels}) ` +
+    `falsePositive=${clip.falsePositive} falseNegative=${clip.falseNegative} ` +
+    `maxTraceDeviation=${clip.maxTraceDeviation.toFixed(6)}drawing-px ` +
+    `maxBindingDeviation=${clip.maxBindingDeviationWorld.toFixed(6)}world-units overshoot=${clip.overshoot.toFixed(6)}drawing-px`,
+  );
+}
+
 /** The lines a build opens on: the cut, then its two input files. */
 export function printBuildHeader(label: string, opts: CompileOptions): void {
   console.log(`rigc build ${label}`);
@@ -2412,7 +2424,7 @@ export function printBuildHeader(label: string, opts: CompileOptions): void {
 }
 
 /** What a compile measured, as `build` reports it before its gate: the parts, the dropped states, the absent parts, the meshes, the physics. */
-export function printCompiled(opts: CompileOptions, result: Pick<CompileResult, 'images' | 'droppedStates' | 'absentParts' | 'meshes' | 'rig' | 'physics'>): void {
+export function printCompiled(opts: CompileOptions, result: Pick<CompileResult, 'images' | 'droppedStates' | 'absentParts' | 'meshes' | 'rig' | 'physics' | 'alphaClips'>): void {
   if (opts.atlasInPath !== undefined) console.log(`  ..    atlas-in ${opts.atlasInPath}`);
   console.log(`  ..    ${result.images.length} part page(s):`);
   for (const img of result.images) {
@@ -2447,6 +2459,7 @@ export function printCompiled(opts: CompileOptions, result: Pick<CompileResult,
   for (const a of result.absentParts) {
     console.log(`  ABSENT ${a.slot}: ${a.why} — slot not emitted`);
   }
+  printAlphaClips(result);
   for (const m of result.meshes) {
     console.log(
       `  MESH  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +