@rig-c/core 2.72.0 → 2.73.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,6 +12524,92 @@ 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.
 
+### 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 1)
 
 rigc poses a model document twice over, on purpose (issue #1591). The **oracle**

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.73.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  ` +

package/src/compile.ts

@@ -34,6 +34,8 @@ import {
   type DepthTone,
 } from './depth.ts';
 import { CompileError, NotImplementedError } from './errors.ts';
+import { alphaClipOutline, clipCarriers, refuseClipCrossing, refuseClipDegeneracy } from './alpha_clip.ts';
+import { regionCorners } from './core/vertices.ts';
 import { parseJsonWithPosition } from './json-position.ts';
 import { hypot2 } from './numeric.ts';
 // The "did you mean" list on a missing atlas region, from the one implementation
@@ -60,6 +62,7 @@ import {
   type RigBone,
   type RigBoundingBoxAttachment,
   type RigClippingAttachment,
+  type RigAlphaClip,
   type RigEvent,
   type RigLinkedMeshAttachment,
   type RigMeshAttachment,
@@ -2296,7 +2299,7 @@ function manifestShapeVisits(manifest: unknown): ShapeVisit[] {
  */
 export function compile(opts: CompileOptions): CompileResult {
   return withDroppedStates((droppedStates) => {
-    const { model, header, atlasText, declaredDurations } = compileInto(opts, droppedStates);
+    const { model, header, atlasText, declaredDurations, alphaClips } = compileInto(opts, droppedStates);
     // The skeleton: the Spine emitter's one entry (issue #922), which writes
     // every section from the model, in the order and under the spellings the
     // file has, and runs the parser-default and key-order passes on the
@@ -2314,6 +2317,7 @@ export function compile(opts: CompileOptions): CompileResult {
       atlasText,
       declaredDurations,
       ...carriedOf(model),
+      ...(alphaClips?.length ? { alphaClips } : {}),
       model,
     };
   });
@@ -2391,6 +2395,7 @@ export function headerBoundsOf(model: CompiledModel, atlasText: string): { box:
  * beside it to gate it, write its document and — if it asks — emit it.
  */
 export interface CompiledBuild {
+  alphaClips?: CompileResult['alphaClips'];
   /** The compiled model (`src/model.ts`), `stage` and `editorOrder` included (issue #1026). */
   model: CompiledModel;
   /** The rest of the Spine header the model does not hold (`SkeletonHeader`): what `compile` hands the emitter beside the model. */
@@ -3012,6 +3017,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   // `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[] | { z: number[]; geometry: DeformGeometry }>();
+  const pendingAlphaClips: PendingAlphaClip[] = [];
   // The same for a `soft` mask's per-vertex level, which a deform envelope's
   // `mask` reads (issue #1413). Never emitted either.
   const attachmentSoftMasks = new Map<string, DeformSoftMask>();
@@ -3212,6 +3218,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
         const where = `skin "${skinName}" slot "${rigSlot.name}" attachment "${placeholder}"`;
         const built = buildRigAttachment(att, placeholder, where, {
           images,
+          pendingAlphaClips,
           bones,
           transforms,
           exactFrames,
@@ -3241,6 +3248,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   // line a linked mesh is the one construct in a rig spec whose name has not been
   // resolved yet.
   resolveLinkedMeshes(pendingLinks, skinTables);
+  const alphaClips = resolveAlphaClips(pendingAlphaClips, skinTables, rig, motion);
   // 📐 The implicit budget of 0 is a statement about rigc's own GENERATORS:
   // geometry rigc built is geometry rigc will not ship unmeasured, and
   // `A13_MESH_BUDGET` has nothing to measure a generated mesh against until the
@@ -3920,6 +3928,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
     header,
     atlasText,
     declaredDurations,
+    ...(alphaClips.length ? { alphaClips } : {}),
   };
 }
 
@@ -4342,6 +4351,7 @@ function refuseDefaultSkinContests(skinNames: readonly string[], skinParts: Map<
 // ---------------------------------------------------------------------------
 
 interface AttachmentContext {
+  pendingAlphaClips: PendingAlphaClip[];
   images: CompiledImage[];
   bones: ModelBone[];
   transforms: Map<string, BoneTransform>;
@@ -4933,6 +4943,273 @@ function buildRigBoundingBox(
   return out;
 }
 
+interface PendingAlphaClip {
+  spec: RigAlphaClip;
+  out: ModelClippingAttachment;
+  where: string;
+  ctx: AttachmentContext;
+}
+
+/** Resolve after all sources/links exist: draw order cannot decide whether a source can be measured. */
+function resolveAlphaClips(
+  pending: PendingAlphaClip[],
+  tables: Map<string, SkinTable>,
+  rig: RigSpec,
+  motion: MotionSpec,
+): NonNullable<CompileResult['alphaClips']> {
+  const reports: NonNullable<CompileResult['alphaClips']> = [];
+  for (const { spec, out, where, ctx } of pending) {
+    const targetTable = tables.get(ctx.skinName)?.[ctx.slotName];
+    const target = Object.entries(targetTable ?? {}).find(([, value]) => value === out)?.[0];
+    // withStatedName can return a fresh object when name was declared.
+    const targetKey = target ?? Object.entries(targetTable ?? {}).find(([, value]) => value.kind === 'clipping' && value.vertices === out.vertices)?.[0];
+    if (targetKey === undefined) {
+      throw new CompileError(
+        `${where}: generated clipping target was not filed in its skin; required a resolved attachment.`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    for (const key of ['slot', 'skin', 'attachment'] as const) {
+      if (typeof spec[key] !== 'string' || spec[key].length === 0) {
+        throw new CompileError(
+          `${where}: alphaClip.${key} is ${JSON.stringify(spec[key])}; required an explicit nonempty source name.`,
+          'CE_COMPILE_ALPHA_CLIP_SOURCE',
+        );
+      }
+    }
+    const sourceWhere = `${spec.skin}/${spec.slot}/${spec.attachment}`;
+    const label = `${where} alphaClip from "${sourceWhere}"`;
+    const source = tables.get(spec.skin)?.[spec.slot]?.[spec.attachment];
+    const sourceSlot = rig.slots.find((slot) => slot.name === spec.slot);
+    if (!source || !sourceSlot) {
+      throw new CompileError(
+        `${label}: source attachment is absent; required a declared slot/skin/attachment.`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    if (source.kind !== 'region' && source.kind !== 'mesh' && source.kind !== 'linkedmesh') {
+      throw new CompileError(
+        `${label}: source kind is ${source.kind}; required a region or resolved mesh with pixels.`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    let geometry: SkinTableEntry = source;
+    let depthKey = sourceWhere;
+    if (geometry.kind === 'linkedmesh') {
+      depthKey = `${geometry.skin}/${geometry.slot}/${geometry.source}`;
+      const base = tables.get(geometry.skin)?.[geometry.slot]?.[geometry.source];
+      if (!base || base.kind !== 'mesh') {
+        throw new CompileError(
+          `${label}: linked source resolves to ${base?.kind ?? 'nothing'}; required a resolved mesh.`,
+          'CE_COMPILE_ALPHA_CLIP_SOURCE',
+        );
+      }
+      geometry = base;
+    }
+    if (geometry.kind !== 'region' && geometry.kind !== 'mesh') {
+      throw new CompileError(
+        `${label}: source is ${(geometry as SkinTableEntry).kind}; required region or mesh geometry with a plate (a clipping source would be a dependency cycle).`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    if (source.sequence !== undefined) {
+      throw new CompileError(
+        `${label}: source has a ${source.sequence.count}-frame sequence; required one immutable source plate. Select a separate named attachment for the measured frame.`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    const region = source.path ?? source.name ?? spec.attachment;
+    const img = ctx.images.find((image) => image.region === region);
+    if (!img) {
+      throw new CompileError(
+        `${label}: region "${region}" has no source plate; required image/atlas pixels.`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    if (img.pageGrid !== undefined) {
+      throw new CompileError(
+        `${label}: source plate grid cannot be located. ${img.pageGrid.sentence}`,
+        'CE_COMPILE_ALPHA_CLIP_SOURCE',
+      );
+    }
+    const plate = partPlate(img);
+    const mask = { width: plate.width, height: plate.height, alpha: plateAlpha(plate) };
+    const traced = alphaClipOutline(mask, spec, label, img.atlasScale ?? 1);
+    const ring = traced.points.map(([x, y]): [number, number] => [x / plate.width, y / plate.height]);
+    const anchor = ctx.transforms.get(sourceSlot.bone)!;
+    let sourceBindings: ModelBinding[][];
+    let uvs: number[];
+    let triangles: number[];
+    if (geometry.kind === 'region') {
+      // Full restored plate, not trimmed page rectangle: source crop pixels remain the coordinates.
+      const corners = regionCorners({ ...geometry, atlas: { width: img.width, height: img.height, originalWidth: img.width, originalHeight: img.height, offsetX: 0, offsetY: 0 } }, anchor);
+      uvs = [0, 1, 0, 0, 1, 0, 1, 1];
+      triangles = [0, 1, 2, 2, 3, 0];
+      sourceBindings = Array.from({ length: 4 }, (_, i) => {
+        const [x, y] = toBoneLocal(anchor, corners[2 * i], corners[2 * i + 1]);
+        return [{ bone: sourceSlot.bone, x, y, weight: 1 }];
+      });
+    } else {
+      uvs = geometry.uvs;
+      triangles = geometry.triangles;
+      const vertices = geometry.vertices;
+      sourceBindings = vertices.weighted ? vertices.bindings :
+        Array.from({ length: vertices.xy.length / 2 }, (_, i) => [{
+          bone: sourceSlot.bone, x: vertices.xy[2 * i], y: vertices.xy[2 * i + 1], weight: 1,
+        }]);
+    }
+    const carried = clipCarriers(ring, uvs, triangles, label);
+    if (carried.points.length > spec.maxVertices) {
+      throw new CompileError(
+        `${label}: polygonoverdeclaredvertexbudget: ${carried.points.length} vertices after source carrier crossings (${traced.points.length} simplified), required <=${spec.maxVertices}. Raise the declared budget or simplify the source/outline.`,
+        'CE_COMPILE_ALPHA_CLIP_VERTEX_BUDGET',
+      );
+    }
+    // Per-bone first moments preserve Σβ Σw M(bind) for every bone matrix; no solver or new pose model.
+    const bindings: ModelBinding[][] = carried.carriers.map((carrier) => {
+      const moments = new Map<string, { weight: number; x: number; y: number }>();
+      carrier.corners.forEach((index, corner) => {
+        for (const binding of sourceBindings[index]) {
+          const share = carrier.bary[corner] * binding.weight;
+          const row = moments.get(binding.bone) ?? { weight: 0, x: 0, y: 0 };
+          row.weight += share;
+          row.x += share * binding.x;
+          row.y += share * binding.y;
+          moments.set(binding.bone, row);
+        }
+      });
+      const result: ModelBinding[] = [];
+      for (const [bone, row] of moments) {
+        if (row.weight > 0) {
+          result.push({ bone, weight: f32(row.weight), x: f32(row.x / row.weight), y: f32(row.y / row.weight) });
+        }
+      }
+      return result;
+    });
+    out.vertices = { weighted: true, bindings };
+    out.vertexCount = bindings.length;
+    const mappedWorld = setupWorldVertices(out.vertices, anchor, ctx.transforms, label)
+      .map(([x, y]): [number, number] => [Math.fround(x), Math.fround(y)]);
+    refuseClipDegeneracy(mappedWorld, `${label} final float32 world coordinates`);
+    refuseClipCrossing(mappedWorld, label);
+    const sourceWorld = sourceBindings.map((vertex): [number, number] => {
+      let x = 0;
+      let y = 0;
+      for (const binding of vertex) {
+        const [wx, wy] = toWorld(ctx.transforms.get(binding.bone)!, binding.x, binding.y);
+        x += binding.weight * wx;
+        y += binding.weight * wy;
+      }
+      return [x, y];
+    });
+    let maxBindingDeviationWorld = 0;
+    carried.carriers.forEach((carrier, index) => {
+      let x = 0;
+      let y = 0;
+      carrier.corners.forEach((corner, k) => {
+        x += carrier.bary[k] * sourceWorld[corner][0];
+        y += carrier.bary[k] * sourceWorld[corner][1];
+      });
+      maxBindingDeviationWorld = Math.max(
+        maxBindingDeviationWorld,
+        hypot2(mappedWorld[index][0] - x, mappedWorld[index][1] - y),
+      );
+    });
+    const filed = targetTable![targetKey];
+    if (filed.kind === 'clipping') {
+      filed.vertices = out.vertices;
+      filed.vertexCount = out.vertexCount;
+    }
+    // Authored depth turns use setup-world geometry, even for a rigid source.
+    // Preserve that frame on the clip's own vertex/influence roster, not the source's.
+    const sourceDepth = ctx.depths.get(depthKey);
+    const z = sourceDepth === undefined || Array.isArray(sourceDepth) ? sourceDepth : sourceDepth.z;
+    let clipDepthGeometry: DeformGeometry | undefined;
+    if (z !== undefined) {
+      const depths = carried.carriers.map((carrier) =>
+        carrier.corners.reduce((sum, vertex, i) => sum + carrier.bary[i] * z[vertex], 0));
+      if (sourceDepth !== undefined && !Array.isArray(sourceDepth)) {
+        clipDepthGeometry = {
+          ...deformGeometryOf(out, label, ctx.transforms, ctx.transforms.get(ctx.anchorBone)!),
+          depth: depths,
+        };
+      }
+      ctx.depths.set(`${ctx.skinName}/${ctx.slotName}/${targetKey}`,
+        clipDepthGeometry === undefined ? depths : { z: depths, geometry: clipDepthGeometry });
+    }
+    // The helper, not the number of distinct bone names, defines the frame.
+    // Duplicate influences on one bone also take the world-space path.
+    const frameOf = (attachment: ModelVertexAttachment, unweightedBone: string, depthGeometry: DeformGeometry | undefined,
+      key: MotionDeformTrack['keys'][number] | undefined): {
+      name: string; geometry: DeformGeometry;
+    } => {
+      // Match compileDeformTrack's per-key choice, including authored depth:true.
+      const geometry = (key?.transform !== undefined && 'depth' in key.transform && key.transform.depth === true
+        ? depthGeometry : undefined) ?? deformGeometryOf(attachment, label, ctx.transforms);
+      const vertices = attachment.vertices;
+      const bone = vertices.weighted ? vertices.bindings[0]?.[0]?.bone : unweightedBone;
+      return { name: geometry.influenceBones === null ? `bone:${bone}` : 'world', geometry };
+    };
+    for (const [animationName, animation] of Object.entries(motion.animations ?? {})) {
+      const sourceIdentity = source.kind === 'linkedmesh' && source.timelines ? depthKey : sourceWhere;
+      const targetIdentity = `${ctx.skinName}/${ctx.slotName}/${targetKey}`;
+      const sourceTrack = animation.deform?.find((track) =>
+        `${track.skin ?? 'default'}/${track.slot}/${track.attachment}` === sourceIdentity);
+      const clipTrack = animation.deform?.find((track) =>
+        `${track.skin ?? 'default'}/${track.slot}/${track.attachment}` === targetIdentity);
+      if (!sourceTrack && !clipTrack) continue;
+      const sourceDepthGeometry = sourceDepth !== undefined && !Array.isArray(sourceDepth) ? sourceDepth.geometry : undefined;
+      const frames = (sourceTrack?.keys.length ? sourceTrack.keys : [undefined]).map((key, index) => ({
+        source: geometry.kind === 'mesh' ? frameOf(geometry, sourceSlot.bone, sourceDepthGeometry, key) : null,
+        clip: frameOf(out, ctx.anchorBone, clipDepthGeometry, clipTrack?.keys[index]),
+      }));
+      const compatible = frames.every(({ source, clip }) => source !== null && source.geometry.setup !== null &&
+        clip.geometry.setup !== null && source.name === clip.name);
+      const { source: sourceFrame, clip: clipFrame } = frames.find(({ source, clip }) =>
+        source === null || source.geometry.setup === null || clip.geometry.setup === null || source.name !== clip.name) ?? frames[0];
+      // With a world-space deform, varying per-vertex influence shares would
+      // correlate the deform with moving bone matrices. Constant shares commute
+      // with the affine/depth projection; no new deformation transfer is implied.
+      const sharesOf = (vertex: ModelBinding[]): string => {
+        const shares = new Map<string, number>();
+        for (const binding of vertex) {
+          shares.set(binding.bone, (shares.get(binding.bone) ?? 0) + binding.weight);
+        }
+        return JSON.stringify([...shares].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+      };
+      const constantWorldShares = !frames.some(({ source }) => source?.name === 'world') ||
+        sourceBindings.every((vertex) => sharesOf(vertex) === sharesOf(sourceBindings[0]));
+      const shared = sourceTrack !== undefined && clipTrack !== undefined &&
+        JSON.stringify(sourceTrack.keys) === JSON.stringify(clipTrack.keys);
+      const linear = sourceTrack?.keys.every((key) => {
+        const transform = key.transform;
+        return transform !== undefined && transform.envelope === undefined &&
+          (transform.kind === 'affine' || ((transform.kind === 'yaw' || transform.kind === 'pitch') &&
+            transform.depth === true && z !== undefined));
+      });
+      if (!shared || !linear || !compatible || !constantWorldShares) {
+        throw new CompileError(
+          `${label}: animation "${animationName}" has ${sourceTrack?.keys.length ?? 0} source and ` +
+            `${clipTrack?.keys.length ?? 0} clip keys; source frame=${sourceFrame?.name ?? 'no vertex geometry'}, ` +
+            `clip frame=${clipFrame.name}, constant world influence shares=${constantWorldShares}. ` +
+            'Required matching explicit affine/depth-yaw/pitch transforms in compatible DeformGeometry frames, ' +
+            'with constant shares for world-space transfer. Fix the named frame/keys or author corresponding clip motion.',
+          'CE_COMPILE_ALPHA_CLIP_DEFORM',
+        );
+      }
+    }
+    reports.push({
+      target: `${ctx.skinName}/${ctx.slotName}/${targetKey}`,
+      source: sourceWhere,
+      ...traced.report,
+      vertices: out.vertexCount,
+      uvs: carried.points,
+      maxBindingDeviationWorld,
+    });
+  }
+  return reports;
+}
+
 function buildRigClipping(
   att: RigClippingAttachment,
   where: string,
@@ -4956,9 +5233,15 @@ function buildRigClipping(
     ...(att.end !== undefined ? { end: att.end } : {}),
     ...(att.convex !== undefined ? { convex: att.convex } : {}),
     ...(att.inverse !== undefined ? { inverse: att.inverse } : {}),
-    vertexCount: att.vertexCount,
-    vertices: buildVertexGeometry(att, where, ctx),
+    vertexCount: att.vertexCount ?? 0,
+    vertices: att.alphaClip === undefined ? buildVertexGeometry({ ...att, vertexCount: att.vertexCount! }, where, ctx) : { weighted: false, xy: [] },
   };
+  if (att.alphaClip !== undefined) {
+    const fields = ['vertexCount', 'vertices', 'weights', 'boneIndexing'] as const;
+    const present = fields.filter((key) => att[key] !== undefined);
+    if (present.length || att.convex === true || att.inverse === true) throw new CompileError(`${where}: alphaClip conflicts with [${present.join(', ')}], convex=${att.convex}, inverse=${att.inverse}; required ordinary inside clipping with generated geometry only. Remove authored geometry/flags.`, 'CE_COMPILE_ALPHA_CLIP_CONFLICT');
+    ctx.pendingAlphaClips.push({ spec: att.alphaClip, out, where, ctx });
+  }
   if (att.color !== undefined) out.editorColor = att.color;
   return out;
 }

package/src/core/clipping.ts

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

package/src/mesh.ts

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

package/src/rig.ts

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

package/src/types.ts

@@ -1562,7 +1562,33 @@ export interface DroppedState {
   why?: string;
 }
 
+/** Alpha-derived clipping fit, on the source plate's pixel-centre grid. */
+export interface AlphaClipReport {
+  target: string;
+  source: string;
+  alpha: number;
+  tolerance: number;
+  maxVertices: number;
+  tracedVertices: number;
+  simplifiedVertices: number;
+  vertices: number;
+  artPixels: number;
+  coveredArt: number;
+  coverage: number;
+  falsePositive: number;
+  falseNegative: number;
+  /** Original trace-corner distance to simplified outline, in drawing pixels, before binding. */
+  maxTraceDeviation: number;
+  /** Maximum setup-world displacement caused by final float32 bind/world rounding, in world units. */
+  maxBindingDeviationWorld: number;
+  overshoot: number;
+  /** source normalized UVs in the emitted clipping vertex order, including carrier crossings. */
+  uvs: Array<[number, number]>;
+}
+
 export interface CompileResult {
+  /** Present only for generated clipping; does not alter emitted model/skeleton geometry. */
+  alphaClips?: AlphaClipReport[];
   /**
    * The compiled model (`src/model.ts`): what the skeleton below was emitted
    * from. This cut fills its `bones` and `setupWorld`; every other field is