@rig-c/core 2.78.0 → 2.80.0

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/rig-c"><img src="https://img.shields.io/npm/v/rig-c.svg?style=flat-square&color=FF6B4A" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@rig-c/core"><img src="https://img.shields.io/npm/v/@rig-c/core.svg?style=flat-square&color=FF6B4A" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/rig-c"><img src="https://img.shields.io/npm/dm/rig-c.svg?style=flat-square&color=A855F7" alt="npm downloads" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-38BDF8.svg?style=flat-square" alt="license" /></a>
 </p>
@@ -14,9 +14,9 @@ format, with rigc's own compiled model beside it —
 gated by a list of named assertions before a byte is written — rigc's own validator in
 the published package, held to a `spine-core` round trip's verdicts in this
 repository's CI. Built so AI agents can author rigs and check their own work; it ships
-as an agent skill. On npm it is `rig-c` — the same package as `spine-rigc`, the name it
-first shipped under, and as `@rig-c/core`, its name under the toolchain's scope, both
-published beside it with the same files at every version.
+as an agent skill. Its canonical npm package is `@rig-c/core`, under the toolchain's
+scope. `rig-c` is the convenience install name; `spine-rigc` is the legacy install
+name. Both remain published alongside it with the same product files.
 
 ## What you get
 
@@ -177,22 +177,23 @@ name with exit 2 before upload. Use a published exact `X.Y.Z` (no `v` prefix,
 alias, range or prerelease), or retry a failed network fetch. This is repository
 verification tooling, not an installed `rigc` command or a change to CI's matrix.
 
-**The npm package is `rig-c`; the command it installs is `rigc`.** npm
+**The canonical npm package is `@rig-c/core`; the command it installs is `rigc`.**
+`rig-c` remains a convenience install name. npm
 refuses the name `rigc` as too similar to packages that already exist, so the
-project and the executable keep their name and the registry entry carries one
-hyphen; the repository is [`rig-c/core`](https://github.com/rig-c/core). **`spine-rigc` is the same package**: it is the name
+project and the executable keep their name; the convenience name `rig-c` carries one
+hyphen; the repository is [`rig-c/core`](https://github.com/rig-c/core). **`spine-rigc` is the legacy install name for the same package**: it is the name
 every version up to 2.20.4 shipped under, and it stays published as an alias —
 every version from 2.20.4 on is on both names, with the same files — so a
 project that depends on `spine-rigc` keeps receiving every release. A new
-project installs `rig-c`; `@rig-c/core` is the same package under the scope.
+project installs `@rig-c/core`, the canonical package under the toolchain's scope.
 
 ```bash
-bunx rig-c --help    # run it without installing
-bun add -g rig-c     # or install the command
-bun add -d rig-c     # or pin it in a project
+bunx @rig-c/core --help    # run it without installing
+bun add -g @rig-c/core     # or install the command
+bun add -d @rig-c/core     # or pin it in a project
 ```
 
-`npx rig-c` works too, as long as Bun is on `PATH` — the executable is a
+`npx @rig-c/core` works too, as long as Bun is on `PATH` — the executable is a
 Bun script, and npm only writes the shim that calls it.
 
 Installed, the command is `rigc`. The examples below spell it `bun cli.ts`
@@ -242,7 +243,7 @@ plugin marketplace:
 /plugin install rigc@rigc
 ```
 
-With the package already installed, `claude --plugin-dir node_modules/rig-c`
+With the package already installed, `claude --plugin-dir node_modules/@rig-c/core`
 loads the same skills without a marketplace. The plugin carries no version of its
 own — `/plugin update` follows `main` commit by commit, and the only version on
 disk stays the one in `package.json`.
@@ -254,8 +255,8 @@ Codex, Gemini CLI and Antigravity read skills from one directory in the workspac
 `node_modules`. With the package installed, one command puts every skill there:
 
 ```shell
-bun add -d rig-c
-bun rigc skills install          # relative links: .agents/skills/rigc -> ../../node_modules/rig-c/skills/rigc
+bun add -d @rig-c/core
+bun rigc skills install          # relative links: .agents/skills/rigc -> ../../node_modules/@rig-c/core/skills/rigc
 bun rigc skills install --copy   # the folders themselves, for a host that does not follow a link
 ```
 
@@ -290,11 +291,11 @@ reference export, so nothing you read in a quickstart is an answer to anything
 **1. Install the command.**
 
 ```bash
-bun add -g rig-c     # installs `rigc`
+bun add -g @rig-c/core     # installs `rigc`
 ```
 
 Or skip the install and prefix every command below with `bunx `, e.g.
-`bunx rig-c build …`.
+`bunx @rig-c/core build …`.
 
 **2. Make a directory and three plates.** rigc measures PNGs rather than trusting
 a number you typed (R5), so the art has to exist. These three are solid colours a

package/docs/AUTHORING.md

@@ -11267,6 +11267,27 @@ Everything above is what the editor **does**. This is what it **returns** — wh
 matters to you for one reason: a construct nobody has carried through the editor
 is a construct that might vanish there, and an agent cannot see that it did.
 
+`tools/editor_roundtrip.ts` also names a clipping semantic change after export
+(issue #1630), including under `--exported`. If the export adds `convex: true`
+where the same skin/slot/attachment in the build did not state true, and the
+build's authored setup polygon has a reflex vertex, it prints:
+
+```text
+FAIL  EDITOR_ADDED_CONVEX_ON_CONCAVE_CLIP skin "S" slot "C" attachment "A" end "E": export convex=true, build convex is not true; setup reflex vertices=N; the editor's export clips with the convex hull of the authored concave polygon
+```
+
+The setup polygon is read through the runtime with that skin applied, setup
+bones and constraints posed, and the slot's deform empty, as for the renderer's
+authored rest geometry. Weighted vertex runs are therefore read as posed points,
+not mistaken for coordinate pairs; animation-time deformation is not substituted
+for the authored setup shape. Reflex turns are counted in either winding and
+straight boundary vertices do not make a convex polygon concave. A convex setup
+polygon or a build already stating `convex: true` adds no line. The named failure
+makes the trip exit nonzero **after** the existing per-skin render/check figures
+are printed; it does not replace those measurements. It changes neither compiler
+emission nor coordinates, and does not imply that removing the export's flag
+undoes the editor's other changes.
+
 🔬 The source is one run: eight discriminator rigs, each built to isolate a group
 of fields, compiled by rigc **0.21.0** (emitting 4.3.13), imported into a licensed
 Spine **4.3.26** through the documented CLI and exported back, with the
@@ -12647,7 +12668,7 @@ verdict on those figures.
 | <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 5)
+## 15. Posing in place for a player — the runtime poser (stage 9)
 
 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,
@@ -12682,16 +12703,31 @@ 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 5 poses |
+| | what stage 9 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`, light colour (`rgba`, `rgb`, `alpha`) and dark colour (`rgba2`, `rgb2`); `drawOrder`; ik, transform and path timelines; linear, stepped and Bézier keys, each read from a per-pose key cursor |
-| constraints | physics with its exact clock, reset and parameter timelines, and optional constraint-scoped external translate/rotate; value-mapped sliders with bone/slot/draw-order/deform/physics composition; path constraints across all position, spacing and rotate modes on open or closed, constant-speed or arc-length, weighted or unweighted, deformed curves; 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 |
+| constraints | physics with its exact clock, reset and parameter timelines, and optional constraint-scoped external translate/rotate; value-mapped sliders with bone/slot/draw-order/deform/physics composition; path constraints across all position, spacing and rotate modes on open or closed, constant-speed or arc-length, weighted or unweighted, deformed curves; one- and two-bone ik; absolute/additive transform constraints with local or world sources and targets; 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 and path 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) |
 
+Clipping draw output is read by `pose.computeClipped()`. It recomputes vertices
+and overwrites `pose.clipping`'s preallocated `clipSlots`, `drawSlots` and per-slot
+`outputs`, with `clipCount` and `drawCount` delimiting live rows. `pose.clipping`
+is null on a model without clipping. Only draws under an active clip appear
+there; this is not the complete draw list. Each output has vertex/triangle
+counts, float32 coordinates and UVs, triangle indices, source triangle indices
+and the cut flag. Slot-end/start order follows `poseClipped`; polygon planning
+and arithmetic follow `clipShapeOf`, `clipThrough` and `clipTriangles`.
+Concave/inverse rows follow the core's drawn coverage. The oracle's native
+triangle list is absent there, so the third dumper refuses that reading as
+`oracle-absent` rather than relabeling coverage. Self-crossing, unsupported
+repeated vertices, collapsed polygons and non-finite clipped coordinates or
+UVs are rejected when the polygon is prepared or clipped, as the core rejects
+those inputs; no arbitrary-polygon or singular-input coverage is claimed.
+
 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,
@@ -12767,9 +12803,41 @@ constraints later in update order. An unsupported timeline in a slider's
 animation refuses the whole model under that timeline's existing feature name,
 so an unselected track cannot hide a construct the slider always applies.
 
+Transform constraints read each source property from the current local
+values (`localSource: true`) or world matrix, including earlier constraints'
+read-back, apply offsets and cross-mappings in declaration order, then clamp and
+blend by the keyed property mix. `localTarget: true` writes local values and
+re-poses the changed bones and their descendants in bone order without a world
+read-back; world targets keep their edited world matrices and read back locals.
+A zero mix leaves that property untouched. Both local and world targets accept
+all five inherit modes. For a parented `noScale` or `noScaleOrReflection` world
+target, read-back derives rotation from the parent's adjugate and the edited
+world x column, rebuilds that mode's normalised frame, and decomposes the world
+columns in it. The residual x angle is kept as `shearX`; `noScale` preserves a
+parent reflection and `noScaleOrReflection` removes it. This is the oracle's
+`localFromWorld`, `noScaleDirection` and `decompose` order; subsequent local
+readers and parent edits observe those same locals. Stage-seven controls
+`RP43`–`RP46` hold both modes to the oracle with omission and allocation plants.
+With `additive: true`, a local position, rotation or shear adds `v * mix`
+and a local scale multiplies by `1 + (v - 1) * mix`. A world rotation turns by
+`v * RAD` wrapped once at the runtime pi before applying mix; world translation
+adds `v * mix`, and world scale multiplies by `1 + (v - 1) * mix` (a zero-length
+column is left alone). World additive shear uses `(v + 90) * RAD - 90 * RAD`
+without wrapping, then adds the mixed angle to the existing y-column angle.
+That subtraction order is kept exactly, as in the oracle's `applyWorld`;
+replacing it with `v * RAD` is not bit-equivalent. Source reading, mappings,
+clamp, keyed mixes and the final union repose retain `solveTransform` order.
+Stage-nine controls `RP53`–`RP56` compare buffered primitives and default
+admission to the oracle, require every omission to differ, and measure pose
+stepping plus clipping with a per-frame object plant. Stage-eight controls
+`RP47`–`RP52` hold all four source/target forms to the
+oracle, with an omission plant and the steady-state allocation meter.
+Stage-six controls `RP38`–`RP42` hold local-source, local-target
+and both forms to the oracle with omission and allocation plants.
+
 **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 5), N construct(s) missing:
+reads `not posed by the runtime poser (stage 9), 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
@@ -12778,10 +12846,8 @@ refused: nothing is posed approximately.
 
 | feature | refuses | what it is |
 | --- | --- | --- |
-| `local-transform`, `additive-transform` | the model | a transform constraint with `localSource` or `localTarget`, or `additive` |
 | `inactive-constrained-bone` | the model | an applied ik, transform or path constraint naming a bone the view leaves inactive (what the oracle writes there depends on the pass before) |
-| `noscale-world-target` | the model | a world-space transform onto a `noScale` or `noScaleOrReflection` bone, whose local values would be read back in that mode |
-| `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` |
+| `null-atlas-region` | the model when shown at setup, else the animation that keys it | 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`, `pathAnimationsWhy`, `steppedPreviousPassWhy`, `sliderDeformsWalkedPathWhy`) |
 | `inherit-timeline`, `sequence-timeline` | the animation | a timeline of that kind |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.78.0",
+  "version": "2.80.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/skills/rigc/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc
 description: Author, build and validate Spine 4.3 skeleton data (skeleton.json plus its .atlas) from loose part PNGs with rigc, the rig compiler that verifies its own output with named assertions before writing it. Use for any request to make a Spine rig or Spine animation from PNG parts, or where the source is a Live2D, Unity or video model whose pictures you can render, to run or read rigc build, validate, render, preview, check or vote, or to write or fix a *.rig.json or *.motion.json spec; it says which shipped guide to open for the need at hand. Not for Live2D conversion, cutting an illustration into parts, or real-time face tracking.
 license: MIT
-compatibility: Requires Bun 1.4 or later. The tool is the npm package rig-c (bunx rig-c, or bun add -d rig-c); the command it installs is rigc.
+compatibility: Requires Bun 1.4 or later. The canonical npm package is @rig-c/core (bunx @rig-c/core, or bun add -d @rig-c/core); the command it installs is rigc. rig-c is the convenience install name; spine-rigc is the legacy install name.
 ---
 
 # rigc — a rig compiler for agents
@@ -46,8 +46,8 @@ index within that same limit; only legacy uncoded library errors point at `§5.1
 ## Install
 
 ```shell
-bunx rig-c --help       # run it without installing
-bun add -d rig-c        # or pin it in the project; the command is `rigc`
+bunx @rig-c/core --help       # run it without installing
+bun add -d @rig-c/core        # or pin it in the project; the command is `rigc`
 bun rigc skills install      # then link these skills into .agents/skills
 ```
 
@@ -145,8 +145,8 @@ spec files field by field, the emission rules, the loop, and the failure map. Th
 | a **skeleton.json somebody else authored** — read it, repair it, extend it | [INGEST.md](https://github.com/rig-c/core/blob/main/docs/INGEST.md) | `rigc-ingest` |
 | you are the **person operating** the agent rather than the agent | [PROMPTING.md](https://github.com/rig-c/core/blob/main/docs/PROMPTING.md) | — |
 
-Every guide linked here is in the installed package at `node_modules/rig-c/docs/`,
+Every guide linked here is in the installed package at `node_modules/@rig-c/core/docs/`,
 which is the copy that matches the rigc you run; the links go to the repository's
 `main`. Inside the Claude Code plugin the same files are at `${CLAUDE_PLUGIN_ROOT}/docs/`.
 Formats, the CLI reference and the licence chain:
-[README.md](https://github.com/rig-c/core/blob/main/README.md), installed at `node_modules/rig-c/README.md`.
+[README.md](https://github.com/rig-c/core/blob/main/README.md), installed at `node_modules/@rig-c/core/README.md`.

package/src/render.ts

@@ -581,6 +581,28 @@ function setupPosed(data: SkeletonData, skin: string | undefined): Skeleton {
   return skeleton;
 }
 
+/** A named clip's authored setup polygon under its own skin, with no deform. */
+export function setupClipPolygon(
+  data: SkeletonData,
+  skin: string,
+  slotName: string,
+  attachmentName: string,
+): number[] {
+  const skeleton = setupPosed(data, skin);
+  const index = data.findSlot(slotName)?.index ?? -1;
+  const slot = skeleton.slots[index];
+  const attachment = data.findSkin(skin)?.getAttachment(index, attachmentName);
+  if (slot === undefined || !(attachment instanceof ClippingAttachment)) {
+    throw new Error(
+      `setup clip skin ${JSON.stringify(skin)} slot ${JSON.stringify(slotName)} attachment ${JSON.stringify(attachmentName)} did not resolve`,
+    );
+  }
+  slot.appliedPose.deform.length = 0;
+  const polygon = new Array<number>(attachment.worldVerticesLength).fill(0);
+  attachment.computeWorldVertices(skeleton, slot, 0, attachment.worldVerticesLength, polygon, 0, 2);
+  return polygon;
+}
+
 /**
  * Both posers for the skeleton at `skeletonPath` drawn through the atlas at
  * `atlasPath`, with spine-core's parse of it already in hand (`data`) — the

package/src/runtime/clip_draw.ts

@@ -0,0 +1,52 @@
+/** Stage-nine buffered draw walk; RuntimePose owns the frame buffers. */
+import type { RuntimeModel } from './model.ts';
+import type { RuntimePose } from './pose.ts';
+import { RuntimeClipper, RuntimeClipBuffer } from './clipping.ts';
+/** Load once from the same model/view as the pose; frame() overwrites arrays and counts. */
+export class RuntimeDrawClipper {
+  readonly clipSlots: Int32Array;
+  readonly drawSlots: Int32Array;
+  readonly outputs: readonly RuntimeClipBuffer[];
+  nativeRows = true;
+  clipCount = 0;
+  drawCount = 0;
+  private readonly triangles: readonly (Int32Array | null)[];
+  private readonly uvs: readonly (Float64Array | null)[];
+  private readonly clipper: RuntimeClipper;
+  constructor(readonly model: RuntimeModel) {
+    const triangles: Array<Int32Array | null> = [], uvs: Array<Float64Array | null> = [], maxTriangles = new Int32Array(model.slots.length);
+    let maxPolygon = 3;
+    for (const at of model.attachments) {
+      const t = at.clipTopology?.triangles ?? null, uv = at.clipTopology?.uvs ?? null;
+      if (at.clip !== undefined) maxPolygon = Math.max(maxPolygon, at.count / 2);
+      triangles.push(t); uvs.push(uv); if (t !== null) maxTriangles[at.slot] = Math.max(maxTriangles[at.slot], t.length / 3);
+    }
+    this.triangles = triangles; this.uvs = uvs; this.clipper = new RuntimeClipper(maxPolygon);
+    this.clipSlots = new Int32Array(model.slots.length); this.drawSlots = new Int32Array(model.slots.length);
+    this.outputs = Array.from(maxTriangles, n => new RuntimeClipBuffer(n, maxPolygon));
+  }
+  /** pose.computeVertices() must precede this walk. Omission is a diagnostic plant only. */
+  frame(pose: RuntimePose, omit = false): void {
+    if (pose.model !== this.model) throw new Error('runtime clip draw: pose differs from the prepared model');
+    this.clipCount = 0; this.drawCount = 0; this.nativeRows = true;
+    let active = false, end: string | null = null;
+    for (let i = 0; i < pose.drawOrder.length; i++) {
+      const s = pose.drawOrder[i], slot = this.model.slots[s], shown = pose.shown[s], at = shown < 0 ? null : this.model.attachments[shown];
+      if (at?.clip !== undefined) {
+        this.clipSlots[this.clipCount++] = s;
+        if (active && end === slot.name) active = false;
+        if (!omit && !active && this.model.active[at.bone] === 1) {
+          this.clipper.prepare(pose.vertices, at.offset, at.count, at.clip.inverse, at.clip.convex); this.nativeRows &&= this.clipper.nativeRows; active = true; end = at.clip.end;
+        }
+        continue;
+      }
+      if (active && at !== null) {
+        const triangles = this.triangles[shown], uvs = this.uvs[shown];
+        if (triangles !== null && uvs !== null) {
+          this.clipper.clip(pose.vertices, at.offset, triangles, uvs, this.outputs[s]); this.drawSlots[this.drawCount++] = s;
+        }
+      }
+      if (active && end === slot.name) active = false;
+    }
+  }
+}

package/src/runtime/clipping.ts

@@ -0,0 +1,223 @@
+/** Buffered counterpart of clipShapeOf/clipThrough/clipTriangles in src/core/clipping.ts.
+ * RuntimePose.computeClipped overwrites these buffers for the live draw order.
+ * Scratch and outputs are allocated at load; a frame changes counts and array cells only.
+ * Concave/inverse output follows the core's drawn geometry, not an unclaimed Spine triangulation.
+ */
+export class RuntimeClipBuffer {
+  readonly vertices: Float32Array;
+  readonly uvs: Float32Array;
+  readonly triangles: Int32Array;
+  readonly sources: Int32Array;
+  vertexCount = 0;
+  triangleCount = 0;
+  clipped = false;
+  constructor(triangles: number, polygonVertices: number) {
+    const points = triangles * Math.max(3, polygonVertices * (polygonVertices + 3));
+    if (!Number.isSafeInteger(points) || points < 0) throw new Error('runtime clip: output capacity is not a safe non-negative integer');
+    this.vertices = new Float32Array(points * 2); this.uvs = new Float32Array(points * 2);
+    this.triangles = new Int32Array(points * 3); this.sources = new Int32Array(points);
+  }
+}
+
+export class RuntimeClipper {
+  /** Whether the original world polygon has the oracle native convex triangle-list contract. */
+  nativeRows = false;
+  private readonly points: Float64Array;
+  private readonly ring: Int32Array;
+  private readonly work: Int32Array;
+  private readonly sorted: Int32Array;
+  private readonly hull: Int32Array;
+  private readonly pieces: Int32Array;
+  private readonly sizes: Int32Array;
+  private readonly merged: Int32Array;
+  private readonly regions: Float64Array;
+  private readonly regionSizes: Int32Array;
+  private readonly a: Float64Array;
+  private readonly b: Float64Array;
+  private readonly outside: Float64Array;
+  private readonly tri = new Float64Array(6);
+  private readonly uv = new Float64Array(6);
+  private regionsCount = 0;
+  private inverse = false;
+  private cut = false;
+  private n = 0;
+  constructor(readonly maxPolygonVertices: number) {
+    const n = Math.max(3, maxPolygonVertices);
+    this.points = new Float64Array(n * 2); this.ring = new Int32Array(n); this.work = new Int32Array(n);
+    this.sorted = new Int32Array(n); this.hull = new Int32Array(n * 2); this.pieces = new Int32Array(n * n);
+    this.sizes = new Int32Array(n); this.merged = new Int32Array(n * 2);
+    this.regions = new Float64Array(n * n * 2); this.regionSizes = new Int32Array(n);
+    this.a = new Float64Array((n * 2 + 16) * 2); this.b = new Float64Array(this.a.length); this.outside = new Float64Array(this.a.length);
+  }
+  private cross(a: number, b: number, c: number): number {
+    const p = this.points; return (p[b * 2] - p[a * 2]) * (p[c * 2 + 1] - p[a * 2 + 1]) - (p[b * 2 + 1] - p[a * 2 + 1]) * (p[c * 2] - p[a * 2]);
+  }
+  private area(indices: Int32Array, n: number): number {
+    const p = this.points; let area = 0;
+    for (let i = 0; i < n; i++) { const a = indices[i] * 2, b = indices[(i + 1) % n] * 2; area += p[a] * p[b + 1] - p[b] * p[a + 1]; }
+    return area;
+  }
+  private convex(indices: Int32Array, n: number, start = 0): boolean {
+    let sign = 0;
+    for (let i = 0; i < n; i++) {
+      const p = this.points, a = indices[start + i] * 2, b = indices[start + (i + 1) % n] * 2, c = indices[start + (i + 2) % n] * 2;
+      // convexWhy takes the second edge from b, unlike cross3 used by triangulation.
+      const cross = (p[b] - p[a]) * (p[c + 1] - p[b + 1]) - (p[b + 1] - p[a + 1]) * (p[c] - p[b]);
+      if (cross === 0) return false;
+      const next = Math.sign(cross); if (sign === 0) sign = next; else if (sign !== next) return false;
+    }
+    return true;
+  }
+  private on(a: number, b: number, r: number): boolean {
+    const p = this.points; return Math.min(p[a * 2], p[b * 2]) <= p[r * 2] && p[r * 2] <= Math.max(p[a * 2], p[b * 2]) && Math.min(p[a * 2 + 1], p[b * 2 + 1]) <= p[r * 2 + 1] && p[r * 2 + 1] <= Math.max(p[a * 2 + 1], p[b * 2 + 1]);
+  }
+  private meet(a: number, b: number, c: number, d: number): boolean {
+    const d1 = this.cross(c, d, a), d2 = this.cross(c, d, b), d3 = this.cross(a, b, c), d4 = this.cross(a, b, d);
+    if (((d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)) && ((d3 > 0 && d4 < 0) || (d3 < 0 && d4 > 0))) return true;
+    return d1 === 0 && this.on(c, d, a) || d2 === 0 && this.on(c, d, b) || d3 === 0 && this.on(a, b, c) || d4 === 0 && this.on(a, b, d);
+  }
+  private region(indices: Int32Array, n: number, r: number, start = 0): void {
+    const p = this.points; let area = 0;
+    for (let i = 0; i < n; i++) { const a = indices[start + i] * 2, b = indices[start + (i + 1) % n] * 2; area += p[a] * p[b + 1] - p[b] * p[a + 1]; }
+    const base = r * this.maxPolygonVertices * 2;
+    for (let i = 0; i < n; i++) { const j = indices[start + (area > 0 ? n - 1 - i : i)] * 2; this.regions[base + i * 2] = p[j]; this.regions[base + i * 2 + 1] = p[j + 1]; }
+    this.regionSizes[r] = n;
+  }
+  private makeHull(count: number): number {
+    const idx = this.sorted, p = this.points, h = this.hull;
+    for (let i = 0; i < count; i++) {
+      const v = this.ring[i]; let j = i;
+      while (j > 0) { const u = idx[j - 1]; if (p[u * 2] < p[v * 2] || p[u * 2] === p[v * 2] && p[u * 2 + 1] <= p[v * 2 + 1]) break; idx[j] = u; j--; }
+      idx[j] = v;
+    }
+    let used = 0;
+    for (let i = 0; i < count; i++) { const v = idx[i]; while (used >= 2 && this.cross(h[used - 2], h[used - 1], v) <= 0) used--; h[used++] = v; }
+    used--;
+    const lower = used;
+    for (let i = count - 1; i >= 0; i--) { const v = idx[i]; while (used >= lower + 2 && this.cross(h[used - 2], h[used - 1], v) <= 0) used--; h[used++] = v; }
+    return used - 1;
+  }
+  private plan(inverse: boolean, convex: boolean): boolean {
+    this.nativeRows = false;
+    const n = this.n, p = this.points, ring = this.ring;
+    let repeats = 0, distinct = 0;
+    for (let i = 0; i < n; i++) {
+      ring[i] = i;
+      for (let j = i + 1; j < n; j++) if (p[i * 2] === p[j * 2] && p[i * 2 + 1] === p[j * 2 + 1]) repeats++;
+      const j = (i + 1) % n;
+      if (p[i * 2] !== p[j * 2] || p[i * 2 + 1] !== p[j * 2 + 1]) this.work[distinct++] = i;
+    }
+    if (repeats > 0) {
+      if (!inverse && distinct === n - repeats && distinct >= 3 && this.convex(this.work, distinct)) { this.regionsCount = 1; this.inverse = false; this.region(ring, n, 0); return false; }
+      throw new Error('runtime clip: polygon has repeated vertices unsupported by clipShapeOf');
+    }
+    for (let i = 0; i < n; i++) {
+      const j = (i + 1) % n, k = (i + 2) % n;
+      if (this.cross(i, j, k) === 0 && (p[k * 2] - p[j * 2]) * (p[i * 2] - p[j * 2]) + (p[k * 2 + 1] - p[j * 2 + 1]) * (p[i * 2 + 1] - p[j * 2 + 1]) > 0) throw new Error('runtime clip: neighbouring polygon edges fold back');
+      for (let q = i + 2; q < n; q++) if (!(i === 0 && q === n - 1) && this.meet(i, j, q, (q + 1) % n)) throw new Error('runtime clip: polygon edges cross or touch');
+    }
+    const originalConvex = this.convex(ring, n);
+    this.nativeRows = !inverse && originalConvex;
+    let count = n;
+    for (let changed = true; changed && count > 3;) {
+      changed = false;
+      for (let i = 0; i < count; i++) if (this.cross(ring[(i + count - 1) % count], ring[i], ring[(i + 1) % count]) === 0) { ring.copyWithin(i, i + 1, count); count--; changed = true; break; }
+    }
+    if (count === 3 && this.cross(ring[0], ring[1], ring[2]) === 0) throw new Error('runtime clip: every polygon vertex lies on one line');
+    this.inverse = inverse;
+    if (inverse || !originalConvex && convex) { this.regionsCount = 1; this.region(this.hull, this.makeHull(count), 0); return false; }
+    if (originalConvex) { for (let i = 0; i < n; i++) ring[i] = i; this.regionsCount = 1; this.region(ring, n, 0); return false; }
+    if (this.area(ring, count) < 0) for (let i = 0; i < count / 2; i++) { const j = count - 1 - i, v = ring[i]; ring[i] = ring[j]; ring[j] = v; }
+    this.work.set(ring); let left = count, pieces = 0;
+    while (left > 3) {
+      let found = false;
+      for (let k = 0; k < left; k++) {
+        const a = this.work[(k + left - 1) % left], b = this.work[k], c = this.work[(k + 1) % left];
+        if (this.cross(a, b, c) <= 0) continue;
+        let inside = false;
+        for (let j = 0; j < left; j++) { const v = this.work[j]; if (v !== a && v !== b && v !== c && this.cross(a, b, v) >= 0 && this.cross(b, c, v) >= 0 && this.cross(c, a, v) >= 0) { inside = true; break; } }
+        if (inside) continue;
+        const base = pieces * this.maxPolygonVertices; this.pieces[base] = a; this.pieces[base + 1] = b; this.pieces[base + 2] = c; this.sizes[pieces++] = 3;
+        this.work.copyWithin(k, k + 1, left); left--; found = true; break;
+      }
+      if (!found) throw new Error('runtime clip: no ear left in a polygon held simple');
+    }
+    for (let i = 0; i < 3; i++) this.pieces[pieces * this.maxPolygonVertices + i] = this.work[i]; this.sizes[pieces++] = 3;
+    for (let changed = true; changed;) {
+      changed = false;
+      search: for (let a = 0; a < pieces; a++) for (let b = a + 1; b < pieces; b++) {
+        const an = this.sizes[a], bn = this.sizes[b], ab = a * this.maxPolygonVertices, bb = b * this.maxPolygonVertices;
+        for (let i = 0; i < an; i++) {
+          const u = this.pieces[ab + i], v = this.pieces[ab + (i + 1) % an]; let j = -1;
+          for (let k = 0; k < bn; k++) if (this.pieces[bb + k] === v) { j = k; break; }
+          if (j < 0 || this.pieces[bb + (j + 1) % bn] !== u) continue;
+          let size = 0;
+          for (let k = 0; k <= i; k++) this.merged[size++] = this.pieces[ab + k];
+          for (let k = (j + 2) % bn; k !== j; k = (k + 1) % bn) this.merged[size++] = this.pieces[bb + k];
+          for (let k = i + 1; k < an; k++) this.merged[size++] = this.pieces[ab + k];
+          let strict = true;
+          for (let k = 0; k < size; k++) if (this.cross(this.merged[(k + size - 1) % size], this.merged[k], this.merged[(k + 1) % size]) <= 0) { strict = false; break; }
+          if (!strict) continue;
+          for (let k = 0; k < size; k++) this.pieces[ab + k] = this.merged[k]; this.sizes[a] = size;
+          this.pieces.copyWithin(bb, bb + this.maxPolygonVertices, pieces * this.maxPolygonVertices); this.sizes.copyWithin(b, b + 1, pieces); pieces--; changed = true; break search;
+        }
+      }
+    }
+    this.regionsCount = pieces;
+    for (let i = 0; i < pieces; i++) this.region(this.pieces, this.sizes[i], i, i * this.maxPolygonVertices);
+    return pieces > 1;
+  }
+  /** Plan again after float32 conversion exactly when clipThrough first finds pieces. */
+  prepare(polygon: Float64Array, offset: number, count: number, inverse: boolean, convex: boolean): void {
+    this.n = count / 2;
+    if (!Number.isInteger(this.n) || this.n < 3 || this.n > this.maxPolygonVertices) throw new Error('runtime clip: polygon vertex count exceeds its load-time capacity');
+    for (let i = 0; i < count; i++) { const value = polygon[offset + i]; if (!Number.isFinite(value)) throw new Error('runtime clip: polygon contains a non-finite coordinate'); this.points[i] = value; }
+    const replan = this.plan(inverse, convex), nativeRows = this.nativeRows;
+    if (replan) { for (let i = 0; i < count; i++) this.points[i] = Math.fround(polygon[offset + i]); this.plan(inverse, convex); }
+    this.nativeRows = nativeRows;
+  }
+  private half(input: Float64Array, n: number, px: number, py: number, qx: number, qy: number, out: Float64Array): number {
+    let size = 0; this.cut = false; const ex = qx - px, ey = qy - py;
+    for (let i = 0; i < n; i++) {
+      const j = (i + 1) % n, sx = input[i * 2], sy = input[i * 2 + 1], tx = input[j * 2], ty = input[j * 2 + 1];
+      const si = ex * (sy - py) - ey * (sx - px) < 0, ei = ex * (ty - py) - ey * (tx - px) < 0;
+      if (!si || !ei) this.cut = true;
+      if (si !== ei) { const dx = tx - sx, dy = ty - sy, t = (ex * (sy - py) - ey * (sx - px)) / (ey * dx - ex * dy); if (size * 2 + 2 > out.length) throw new Error('runtime clip: scratch polygon exceeds its load-time capacity'); out[size * 2] = sx + t * dx; out[size * 2 + 1] = sy + t * dy; size++; }
+      if (ei) { if (size * 2 + 2 > out.length) throw new Error('runtime clip: scratch polygon exceeds its load-time capacity'); out[size * 2] = tx; out[size * 2 + 1] = ty; size++; }
+    }
+    return size;
+  }
+  private emit(points: Float64Array, count: number, cut: boolean, source: number, out: RuntimeClipBuffer): void {
+    if (count < 3) return;
+    if ((out.vertexCount + count) * 2 > out.vertices.length || out.triangleCount + count - 2 > out.sources.length) throw new Error('runtime clip: output exceeds its load-time capacity');
+    const tri = this.tri, uv = this.uv, base = out.vertexCount;
+    const d0 = tri[3] - tri[5], d1 = tri[4] - tri[2], d2 = tri[0] - tri[4], d4 = tri[5] - tri[1], d = 1 / (d0 * d2 + d1 * (tri[1] - tri[5]));
+    for (let i = 0; i < count; i++) {
+      const x = cut ? points[i * 2] : tri[i * 2], y = cut ? points[i * 2 + 1] : tri[i * 2 + 1], at = out.vertexCount++ * 2;
+      out.vertices[at] = x; out.vertices[at + 1] = y;
+      if (!cut) { out.uvs[at] = uv[i * 2]; out.uvs[at + 1] = uv[i * 2 + 1]; }
+      else { const a = (d0 * (x - tri[4]) + d1 * (y - tri[5])) * d, b = (d4 * (x - tri[4]) + d2 * (y - tri[5])) * d, c = 1 - a - b; out.uvs[at] = uv[0] * a + uv[2] * b + uv[4] * c; out.uvs[at + 1] = uv[1] * a + uv[3] * b + uv[5] * c; }
+    }
+    for (let i = base * 2; i < out.vertexCount * 2; i++) if (!Number.isFinite(out.vertices[i]) || !Number.isFinite(out.uvs[i])) throw new Error(`runtime clip: triangle ${source} produced a non-finite clipped coordinate or UV`);
+    for (let i = 1; i + 1 < count; i++) { const at = out.triangleCount * 3; out.triangles[at] = base; out.triangles[at + 1] = base + i; out.triangles[at + 2] = base + i + 1; out.sources[out.triangleCount++] = source; }
+  }
+  clip(vertices: Float64Array, offset: number, triangles: Int32Array, uvs: Float64Array, out: RuntimeClipBuffer): void {
+    out.vertexCount = 0; out.triangleCount = 0; out.clipped = this.inverse;
+    for (let k = 0; k < triangles.length; k += 3) {
+      for (let j = 0; j < 3; j++) { const n = triangles[k + j] * 2; this.tri[j * 2] = vertices[offset + n]; this.tri[j * 2 + 1] = vertices[offset + n + 1]; this.uv[j * 2] = Math.fround(uvs[n]); this.uv[j * 2 + 1] = Math.fround(uvs[n + 1]); }
+      if (!this.inverse) for (let r = 0; r < this.regionsCount; r++) {
+        let input = this.a, output = this.b, count = 3, cut = false; for (let i = 0; i < 6; i++) input[i] = this.tri[i];
+        const n = this.regionSizes[r], base = r * this.maxPolygonVertices * 2;
+        for (let e = 0; e < n && count > 0; e++) { const p = base + e * 2, q = base + ((e + 1) % n) * 2; count = this.half(input, count, this.regions[p], this.regions[p + 1], this.regions[q], this.regions[q + 1], output); cut ||= this.cut; const swap = input; input = output; output = swap; }
+        out.clipped ||= cut; this.emit(input, count, cut, k / 3, out);
+      } else {
+        let input = this.a, output = this.b, count = 3, cutSoFar = false; for (let i = 0; i < 6; i++) input[i] = this.tri[i];
+        const n = this.regionSizes[0];
+        for (let e = 0; e < n && count > 0; e++) { const p = e * 2, q = ((e + 1) % n) * 2, px = this.regions[p], py = this.regions[p + 1], qx = this.regions[q], qy = this.regions[q + 1];
+          const outside = this.half(input, count, qx, qy, px, py, this.outside), cut = this.cut || cutSoFar; this.emit(this.outside, outside, cut, k / 3, out);
+          count = this.half(input, count, px, py, qx, qy, output); cutSoFar ||= this.cut; const swap = input; input = output; output = swap;
+        }
+      }
+    }
+  }
+}

package/src/runtime/index.ts

@@ -21,13 +21,13 @@
  * corpus through both at the oracle's samples and compares full doubles at
  * tolerance 0 (*The runtime poser* there). The oracle is not changed for it.
  *
- * ## Stage 5: what it poses, and what it refuses
+ * ## Stage 8: what it poses, and what it refuses
  *
  * Bones and their five inherit modes; the rotate, translate, scale and shear
  * timelines; a slot's attachment, light colour (`rgba`, `rgb`, `alpha`) and
  * dark colour (`rgba2`, `rgb2`) timelines; draw-order timelines (including
  * slider draw-order application); weighted/unweighted deform timelines; region, mesh, weighted mesh and linked mesh vertices; one- and
- * two-bone ik, world-space absolute transforms, path constraints, physics (with optional movement scope) and value-mapped sliders with their
+ * two-bone ik, absolute/additive transforms with local/world sources and targets in all five inherit modes, path constraints, physics (with optional movement scope) and value-mapped sliders with their
  * timelines; skin-required bones and constraints under the view's skin. One
  * animation at full weight from the setup pose, at a time or stepped as a
  * looping track. Everything else is refused at load by name with the list of

package/src/runtime/model.ts

@@ -1,5 +1,5 @@
 /**
- * The runtime poser's load-time half (issue #1591, stage 5): a skin view of
+ * The runtime poser's load-time half (issue #1591, stage 9): a skin view of
  * the compiled model (`readModel`, then `underSkin` / `underNoSkin` — the
  * oracle's reader and its views, read and never written) compiled once into
  * index-resolved bones and slots, a constraint plan, compiled timelines and
@@ -12,21 +12,23 @@
  * (`RuntimeMissing`), and:
  *
  * - **refuses the model** (`RuntimeRefusal`, every missing feature listed)
- *   when one is a property of the whole model — a transform constraint reading or
- *   writing local values or adding (`localSource`, `localTarget`,
- *   `additive`), an ik, transform or path constraint over a bone the view leaves
- *   inactive, a world-space transform onto a `noScale` or
- *   `noScaleOrReflection` bone, a clipping attachment or a region with no
+ *   when one is a property of the whole model — an ik, transform or path constraint
+ *   over a bone the view leaves inactive, a region with no
  *   atlas rectangle shown at setup, a placeholder the skins fill
  *   differently, or a block the oracle itself leaves out;
  * - **refuses an animation** (`RuntimeModel.refused`; `animation(name)`
  *   throws the same `RuntimeRefusal`) when the construct is the animation's
  *   — an `inherit` timeline, a sequence timeline, or an
- *   attachment key showing a clipping attachment or a region with no atlas
+ *   attachment key showing a region with no atlas
  *   rectangle. Every other animation of the model is posed.
  *
- * `RUNTIME_FEATURES` is the closed list of what can be named. Stage 5 adds draw-order timelines (including slider draw-order application) and dark-colour (`rgba2`, `rgb2`) timelines on top of Stage 4's path constraints and scoped physics movement. Mesh and path deforms, named/no-skin views
- * and immutable event deliveries remain covered. `ignore: ['events']` remains an explicit diagnostic opt-out; it is
+ * `RUNTIME_FEATURES` is the closed list of what can be named. Stage 9 adds buffered clipping draw output; stage 8 added
+ * additive local/world transform constraints. Stage 7 admitted
+ * world transform targets in both no-scale inherit modes, using the existing
+ * localFromWorld read-back. Stage 6 added local-source and local-target transforms. Draw-order,
+ * light/dark colour, mesh and path deforms, named/no-skin views, path constraints,
+ * scoped physics and immutable event deliveries remain covered.
+ * `ignore: ['events']` remains an explicit diagnostic opt-out; it is
  * never the default. A merged view with conflicting attachments still refuses
  * by name, as the oracle itself cannot resolve that view without file order.
  *
@@ -54,15 +56,11 @@ import type { CoreSliderRecord } from '../core/constraints_slider.ts';
 import { compileCurve, compileDeformCurve, type RuntimeCurve } from './curves.ts';
 
 /** The stage of issue #1591 this poser implements. */
-export const RUNTIME_STAGE = 5;
+export const RUNTIME_STAGE = 9;
 
 /** Every construct the runtime poser can refuse, by the name its refusals carry. */
 export const RUNTIME_FEATURES = [
-  'local-transform',
-  'additive-transform',
   'inactive-constrained-bone',
-  'noscale-world-target',
-  'clipping',
   'null-atlas-region',
   'skin-conflict',
   'oracle-absent',
@@ -130,6 +128,12 @@ export interface RuntimePlant {
   readonly ignorePhysicsScope?: boolean;
   readonly omitDrawOrder?: boolean;
   readonly omitDarkColour?: boolean;
+  /** Omit local-source/target transforms at load, to prove the stage-six gate. */
+  readonly omitLocalTransform?: boolean;
+  /** Omit world transforms with parented no-scale targets, to prove stage seven. */
+  readonly omitNoScaleWorldTransform?: boolean;
+  /** Omit additive transforms at load, to prove stage eight. */
+  readonly omitAdditiveTransform?: boolean;
 }
 
 // A bone's local values, seven per bone.
@@ -200,6 +204,10 @@ export const RAD = RUNTIME_PI / 180;
  * bindings (bone index, float32 coordinates, float32 weight) in their order.
  */
 export interface RuntimeAttachment {
+  /** Source topology resolved at load for models containing clipping. */
+  readonly clipTopology?: { readonly triangles: Int32Array; readonly uvs: Float64Array };
+  /** Clip polygon metadata, resolved once with the attachment. */
+  readonly clip?: { readonly end: string | null; readonly inverse: boolean; readonly convex: boolean };
   /** Source timeline identity, including linked-mesh inheritance, resolved once. */
   readonly timeline: string | null;
   readonly deformOffset: number;
@@ -248,7 +256,7 @@ export interface RuntimeIk {
   readonly flags: number;
 }
 
-/** A world-space, absolute transform constraint as the plan runs it: each source property's offset and its targets'. */
+/** An absolute or additive transform constraint as the plan runs it: each source property's offset and its targets'. */
 export interface RuntimeTransform {
   readonly kind: 'transform';
   readonly name: string;
@@ -268,6 +276,9 @@ export interface RuntimeTransform {
   readonly offsets: Float64Array;
   readonly mixes: Float64Array;
   readonly clamp: boolean;
+  readonly localSource: boolean;
+  readonly localTarget: boolean;
+  readonly additive: boolean;
 }
 
 export interface RuntimePhysics {
@@ -585,20 +596,14 @@ export function compileRuntime(doc: CompiledDocument, options: RuntimeOptions =
     else if (r.kind === 'path') {
       constraints.push(compilePath(r, index, applied, bones, indexOf, slotIndexOf, pathPlan.get(index) ?? null));
     } else {
-      if (r.localSource || r.localTarget) refusals.note('local-transform', `transform constraint "${r.name}" ${[r.localSource ? 'reads local values (localSource)' : '', r.localTarget ? 'writes local values (localTarget)' : ''].filter((x) => x !== '').join(' and ')}`);
-      if (r.additive) refusals.note('additive-transform', `transform constraint "${r.name}" is additive`);
-      const t = compileTransform(r, index, applied, bones, indexOf);
-      if (applied) {
-        for (let k = 0; k < bones.length; k++) {
-          const m = modes[bones[k]];
-          if (parents[bones[k]] >= 0 && (m === MODE_NO_SCALE || m === MODE_NO_SCALE_OR_REFLECTION)) refusals.note('noscale-world-target', `transform constraint "${r.name}" moves bone "${r.bones[k]}" in world space, and its local values are read back in a noScale mode`);
-        }
-      }
+      const noScaleWorld = !r.localTarget && bones.some(b => parents[b] >= 0 && (modes[b] === MODE_NO_SCALE || modes[b] === MODE_NO_SCALE_OR_REFLECTION));
+      const t = compileTransform(r, index, applied && !(plant.omitLocalTransform && (r.localSource || r.localTarget)) && !(plant.omitNoScaleWorldTransform && noScaleWorld) && !(plant.omitAdditiveTransform && r.additive), bones, indexOf);
       constraints.push(t);
     }
   }
 
   // --- slots and the records they show ---
+  const hasClipping = doc.skins.some(s => Object.values(s.attachments).some(table => Object.values(table).some(at => at.geometry?.kind === 'clipping')));
   const attachments: RuntimeAttachment[] = [];
   let vertexCount = 0;
   let deformCount = 0;
@@ -626,7 +631,9 @@ export function compileRuntime(doc: CompiledDocument, options: RuntimeOptions =
     const at = { timeline: timelineIdentity(slot.name, shown), deformOffset: deformCount, slot: si, name: row.name, skin: shown.skin, placeholder: shown.placeholder, path: CORE_REGION_KINDS.has(shown.record.kind) ? row.path : null, bone: indexOf(slot.bone), offset: vertexCount };
     let made: RuntimeAttachment | null = null;
     let missing: readonly [RuntimeFeature, string] | null = null;
-    if (g?.kind === 'clipping') missing = ['clipping', `slot "${slot.name}" shows clipping attachment "${row.name}"`];
+    if (g?.kind === 'clipping') {
+      made = { ...meshAttachment(at, g.vertices, indexOf, plant.bindingIndex, nb), clip: { end: g.end, inverse: g.inverse, convex: g.convex } };
+    }
     else if (g?.kind === 'region') {
       const r = g.region;
       if (r.atlas === null) missing = ['null-atlas-region', `slot "${slot.name}" shows region "${row.name}", whose atlas rectangle the model states as null`];
@@ -667,6 +674,14 @@ export function compileRuntime(doc: CompiledDocument, options: RuntimeOptions =
     }
     // A bounding box, a refused record admitted by a plant: the row's name and path, and nothing drawn.
     if (made === null) made = vertexAttachment(at, DRAW_NONE, new Float64Array(0), 0);
+    if (hasClipping) {
+      if (g?.kind === 'region') made = { ...made, clipTopology: { triangles: new Int32Array([0, 1, 2, 2, 3, 0]), uvs: new Float64Array([0, 1, 0, 0, 1, 0, 1, 1]) } };
+      else if (g?.kind === 'mesh' || g?.kind === 'linkedmesh') {
+        const mesh = g.kind === 'mesh' ? g : doc.skins.find(s => s.name === g.skin)?.attachments[g.slot]?.[g.source]?.geometry;
+        if (mesh?.kind !== 'mesh') throw new RuntimeInputError('clipping topology: linked source is not a mesh (readModel refuses it first)');
+        made = { ...made, clipTopology: { triangles: Int32Array.from(mesh.triangles), uvs: Float64Array.from(mesh.uvs) } };
+      }
+    }
     attachments.push(made);
     vertexCount += made.count;
     deformCount += made.deformCount;
@@ -882,7 +897,7 @@ function compileTransform(r: CoreTransformRecord, index: number, applied: boolea
     toProperty: Int32Array.from(toProperty), toOffset: Float64Array.from(toOffset), toScale: Float64Array.from(toScale), toMax: Float64Array.from(toMax),
     offsets: Float64Array.from(TRANSFORM_PROPERTIES.map((p) => r.offsets[p])),
     mixes: Float64Array.from(TRANSFORM_PROPERTIES.map((p) => r.mixes[p])),
-    clamp: r.clamp,
+    clamp: r.clamp, localSource: r.localSource, localTarget: r.localTarget, additive: r.additive,
   };
 }
 

package/src/runtime/pose.ts

@@ -1,5 +1,5 @@
 /**
- * The runtime poser's per-instance half (issue #1591, stage 5): one
+ * The runtime poser's per-instance half (issue #1591, stage 9): one
  * `RuntimePose` per skeleton on screen, every buffer allocated when it is
  * made and overwritten in place on every pose, so that posing a frame
  * allocates nothing.
@@ -40,6 +40,7 @@
  * exactly 0 touching nothing; an inactive bone posed as zeros by the
  * hierarchy and never posed again by a constraint, nor the bones below it.
  */
+import { RuntimeDrawClipper } from './clip_draw.ts';
 import type { CorePhysicsRecord } from '../core/constraints_physics.ts';
 import { freshPhysicsState, resetPhysicsState, stepRuntimePhysics, type PhysicsState } from './physics.ts';
 import { COLLAPSED_X_AXIS_SQ, RUNTIME_DEG, RUNTIME_PI } from '../core/world.ts';
@@ -102,6 +103,8 @@ const P_X = 1;
 const P_Y = 2;
 const P_SCALE_X = 3;
 const P_SCALE_Y = 4;
+// `applyLocal` in src/core/constraints.ts: the six transform properties' local fields.
+const PROPERTY_LOCAL = new Int32Array([L_ROTATION, L_X, L_Y, L_SCALE_X, L_SCALE_Y, L_SHEAR_Y]);
 
 /** A change brought once into (−180, 180] — −180 goes to 180 (src/core/constraints.ts). */
 function wrap180(r: number): number {
@@ -136,6 +139,8 @@ export class RuntimePose {
   readonly drawOrder: Int32Array;
   /** Every attachment's world vertices at its `offset`, written by `computeVertices` for the attachments shown. */
   readonly vertices: Float64Array;
+  /** Buffered clipping output; null when the compiled model has no clipping attachments. */
+  readonly clipping: RuntimeDrawClipper | null;
   /** Held/interpolated deform values, one pair per binding when weighted. */
   readonly deform: Float64Array;
   private readonly deformed: Uint8Array;
@@ -190,6 +195,7 @@ export class RuntimePose {
 
   constructor(model: RuntimeModel, options: RuntimePoseOptions = {}) {
     this.model = model;
+    this.clipping = model.attachments.some(at => at.clip !== undefined) ? new RuntimeDrawClipper(model) : null;
     this.clock = options.clock;
     this.hasPhysics = model.constraints.some(c => c.kind === 'physics');
     this.physicsStates = model.constraints.map(() => freshPhysicsState());
@@ -1508,7 +1514,10 @@ export class RuntimePose {
     return true;
   }
 
-  /** A world-space, absolute transform (`solveTransform`): each bone's world edited in turn and written back, then the repose. */
+  /** Absolute/additive transform, matching `solveTransform` in src/core/constraints.ts:
+   * read the source per target/property, edit locals or the scratch world,
+   * then repose the union in bone order (`repose` in that module). No read-back for a local target.
+   */
   private solveTransform(c: RuntimeTransform, k: number): void {
     const W = this.world;
     const w = this.w;
@@ -1538,25 +1547,34 @@ export class RuntimePose {
             v = v < lo ? lo : v > hi ? hi : v;
           }
           applied = true;
-          applyWorld(w, property, v, mix);
+          if (c.localTarget) {
+            const at = bi * LOCALS + PROPERTY_LOCAL[property];
+            const current = this.locals[at];
+            this.locals[at] = c.additive
+              ? property === P_SCALE_X || property === P_SCALE_Y ? current * (1 + (v - 1) * mix) : current + v * mix
+              : current + (v - current) * mix;
+          } else applyWorld(w, property, v, mix, c.additive);
         }
       }
       if (!applied) continue;
-      W[o + W_A] = w[W_A];
-      W[o + W_B] = w[W_B];
-      W[o + W_C] = w[W_C];
-      W[o + W_D] = w[W_D];
-      W[o + W_X] = w[W_X];
-      W[o + W_Y] = w[W_Y];
+      if (!c.localTarget) {
+        W[o + W_A] = w[W_A];
+        W[o + W_B] = w[W_B];
+        W[o + W_C] = w[W_C];
+        W[o + W_D] = w[W_D];
+        W[o + W_X] = w[W_X];
+        W[o + W_Y] = w[W_Y];
+      }
       this.changed[n] = bi;
       this.inWorld[n] = bi;
       n++;
     }
-    if (n > 0) this.repose(n, n);
+    if (n > 0) this.repose(n, c.localTarget ? 0 : n);
   }
 
-  /** The source's world value of a property (`sourceValue`, world source). */
+  /** The source's current local or world value (`sourceValue` in src/core/constraints.ts). */
   private sourceValue(c: RuntimeTransform, property: number): number {
+    if (c.localSource) return this.locals[c.source * LOCALS + PROPERTY_LOCAL[property]] + c.offsets[property];
     const W = this.world;
     const s = c.source * WORLDS;
     const o = c.offsets;
@@ -1640,7 +1658,10 @@ export class RuntimePose {
     if (below[b] === 1 && this.inWorldMark[b] === 0) this.poseBone(b, false);
   }
 
-  /** A bone's local values read back from its world transform (`localFromWorld`) — `normal`, `onlyTranslation` and `noRotationOrReflection`; a world target in a `noScale` mode is refused at load. */
+  /** A bone's locals read back from its world transform (`localFromWorld` in src/core/constraints.ts).
+   * All five inherit modes: the no-scale forms read rotation first, rebuild
+   * `noScaleDirection`, and retain the x-angle residual as shearX in `decompose`.
+   */
   private localFromWorld(bi: number): void {
     const m = this.model;
     const W = this.world;
@@ -1816,6 +1837,14 @@ export class RuntimePose {
     }
   }
 
+  /** Recompute vertices and overwrite clipping output, without per-frame allocation.
+   * Concave/inverse rows describe the core's drawn coverage, not Spine's native triangle list.
+   */
+  computeClipped(): void {
+    this.computeVertices();
+    this.clipping?.frame(this);
+  }
+
   /** Every shown attachment's world vertices into `vertices` at its offset (`regionCorners`, `worldVertices`). */
   computeVertices(): void {
     const m = this.model;
@@ -1889,11 +1918,11 @@ export class RuntimePose {
   }
 }
 
-/** A world-space, absolute transform of one property on a world transform (`applyWorld`). */
-function applyWorld(w: Float64Array, property: number, v: number, mix: number): void {
+/** A world-space absolute/additive property, in `applyWorld` order from src/core/constraints.ts. */
+function applyWorld(w: Float64Array, property: number, v: number, mix: number, additive: boolean): void {
   switch (property) {
     case P_ROTATE: {
-      let r = v * RAD - Math.atan2(w[W_C], w[W_A]);
+      let r = additive ? v * RAD : v * RAD - Math.atan2(w[W_C], w[W_A]);
       if (r > RUNTIME_PI) r -= TWO_PI;
       else if (r < -RUNTIME_PI) r += TWO_PI;
       r *= mix;
@@ -1908,10 +1937,10 @@ function applyWorld(w: Float64Array, property: number, v: number, mix: number):
       return;
     }
     case P_X:
-      w[W_X] = w[W_X] + (v - w[W_X]) * mix;
+      w[W_X] = additive ? w[W_X] + v * mix : w[W_X] + (v - w[W_X]) * mix;
       return;
     case P_Y:
-      w[W_Y] = w[W_Y] + (v - w[W_Y]) * mix;
+      w[W_Y] = additive ? w[W_Y] + v * mix : w[W_Y] + (v - w[W_Y]) * mix;
       return;
     case P_SCALE_X:
     case P_SCALE_Y: {
@@ -1919,7 +1948,7 @@ function applyWorld(w: Float64Array, property: number, v: number, mix: number):
       const q = property === P_SCALE_X ? W_C : W_D;
       const s = Math.sqrt(w[p] * w[p] + w[q] * w[q]);
       if (s === 0) return;
-      const k = 1 + ((v - s) * mix) / s;
+      const k = additive ? 1 + (v - 1) * mix : 1 + ((v - s) * mix) / s;
       w[p] *= k;
       w[q] *= k;
       return;
@@ -1927,8 +1956,9 @@ function applyWorld(w: Float64Array, property: number, v: number, mix: number):
     default: {
       const yAngle = Math.atan2(w[W_D], w[W_B]);
       const xAngle = Math.atan2(w[W_C], w[W_A]);
-      let r = (v + 90) * RAD - (yAngle - xAngle);
-      r = r > RUNTIME_PI ? r - TWO_PI : r < -RUNTIME_PI ? r + TWO_PI : r;
+      // Keep the right-angle subtraction: simplifying it to v * RAD changes bits.
+      let r = (v + 90) * RAD - (additive ? 90 * RAD : yAngle - xAngle);
+      if (!additive) r = r > RUNTIME_PI ? r - TWO_PI : r < -RUNTIME_PI ? r + TWO_PI : r;
       const angle = yAngle + r * mix;
       const s = Math.sqrt(w[W_B] * w[W_B] + w[W_D] * w[W_D]);
       w[W_B] = Math.cos(angle) * s;

package/tools/editor_roundtrip.ts

@@ -917,6 +917,75 @@ export function skinRoster(
   };
 }
 
+/** An attachment's declaration key, kept separate from its skin and slot. */
+interface ClipFlagSkin {
+  name: string;
+  attachments?: Record<string, Record<string, { type?: string; convex?: boolean; end?: string }>>;
+}
+
+/** Reflex turns of the world's own doubles, winding independent; straight turns are not reflex. */
+function reflexVertices(polygon: readonly number[]): number {
+  const n = polygon.length / 2;
+  let area2 = 0;
+  for (let i = 0; i < n; i++) {
+    const j = (i + 1) % n;
+    area2 += polygon[2 * i] * polygon[2 * j + 1] - polygon[2 * j] * polygon[2 * i + 1];
+  }
+  const winding = Math.sign(area2);
+  if (winding === 0) return 0; // Degenerate geometry is the validator's refusal.
+  let count = 0;
+  for (let i = 0; i < n; i++) {
+    const j = (i + 1) % n;
+    const k = (i + 2) % n;
+    const turn =
+      (polygon[2 * j] - polygon[2 * i]) * (polygon[2 * k + 1] - polygon[2 * j + 1]) -
+      (polygon[2 * j + 1] - polygon[2 * i + 1]) * (polygon[2 * k] - polygon[2 * j]);
+    if (turn !== 0 && Math.sign(turn) !== winding) count++;
+  }
+  return count;
+}
+
+/**
+ * An editor-added convex flag changes a concave clip's meaning (issue #1630).
+ * Compare the same skin/slot/attachment, then read the BUILD's posed authored
+ * setup polygon. Weighted runs are not points; an animation deform is not the
+ * authored setup shape. Empty deform follows the renderer's `restOf` convention.
+ * Imports are lazy so the existing no-editor/trial/read refusals need no runtime.
+ */
+async function addedConvexClipFailures(build: string, exported: string, buildDir: string): Promise<string[]> {
+  const before = (JSON.parse(readFileSync(build, 'utf8')) as { skins?: ClipFlagSkin[] }).skins;
+  const after = (JSON.parse(readFileSync(exported, 'utf8')) as { skins?: ClipFlagSkin[] }).skins;
+  const candidates: Array<{ skin: string; slot: string; attachment: string; end: string | null }> = [];
+  for (const skin of Array.isArray(after) ? after : []) {
+    const originalSkin = (Array.isArray(before) ? before : []).find((s) => s.name === skin.name);
+    for (const [slot, attachments] of Object.entries(skin.attachments ?? {})) {
+      for (const [attachment, clip] of Object.entries(attachments)) {
+        const original = originalSkin?.attachments?.[slot]?.[attachment];
+        if (clip.type === 'clipping' && clip.convex === true && original?.type === 'clipping' && original.convex !== true) {
+          candidates.push({ skin: skin.name, slot, attachment, end: original.end ?? null });
+        }
+      }
+    }
+  }
+  if (candidates.length === 0) return [];
+  const { posableFromText, setupClipPolygon } = await import('../src/render.ts');
+  const atlas = readdirSync(buildDir).find((name) => name.endsWith('.atlas'))!;
+  const { data } = posableFromText(readFileSync(build, 'utf8'), readFileSync(join(buildDir, atlas), 'utf8'), buildDir);
+  const lines: string[] = [];
+  for (const candidate of candidates) {
+    const polygon = setupClipPolygon(data, candidate.skin, candidate.slot, candidate.attachment);
+    const reflex = reflexVertices(polygon);
+    if (reflex > 0) {
+      lines.push(
+        `  FAIL  EDITOR_ADDED_CONVEX_ON_CONCAVE_CLIP skin ${JSON.stringify(candidate.skin)} slot ${JSON.stringify(candidate.slot)} ` +
+          `attachment ${JSON.stringify(candidate.attachment)} end ${JSON.stringify(candidate.end)}: export convex=true, build convex is not true; ` +
+          `setup reflex vertices=${reflex}; the editor's export clips with the convex hull of the authored concave polygon`,
+      );
+    }
+  }
+  return lines;
+}
+
 /**
  * One measure of a `diff --json` report as `matched/total (ratio)`, or `null`
  * when the report or the measure is not there — read off the report for the
@@ -1185,7 +1254,7 @@ function imagesProbeFault(skeleton: Record<string, unknown>): string | null {
   return null;
 }
 
-function main(): void {
+async function main(): Promise<void> {
   const opts = parseArgs(process.argv.slice(2));
   const rigc = rigcCommand();
 
@@ -1489,6 +1558,21 @@ function main(): void {
   // console layout for them would break the first time that layout is tidied.
   for (const line of diffSummaryLines(diffJson)) emit(`  ${line}`);
 
+  // Report the changed meaning without skipping any later per-skin figures.
+  let clipFailures: string[];
+  try {
+    // An unreadable export has no semantic comparison. Leave its established
+    // gate/read failure intact (including the late-read planted controls).
+    clipFailures = gate.status === 0 ? await addedConvexClipFailures(source, join(cand, 'skeleton.json'), opts.build) : [];
+  } catch (error) {
+    return fail(`could not measure clipping setup geometry: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (clipFailures.length > 0) {
+    emit('');
+    emit('## 4.1 clipping semantics');
+    for (const line of clipFailures) emit(line);
+  }
+
   // 🔒 The skins come off BOTH files, compared before anything is rendered
   // (issue #801). A skin the export dropped is named here as LOST BY THE EXPORT
   // and fails the run; enumerating the export's skins alone would quietly stop
@@ -1627,7 +1711,7 @@ function main(): void {
   // is the half a single un-skinned check could not say.
   // A version line that disagrees with the export is red too (issue #1199): the
   // report would otherwise name an editor the trip did not run on, green.
-  process.exit(gate.status === 0 && checksClean && rosterClean && !versionDisagrees ? 0 : 1);
+  process.exit(gate.status === 0 && checksClean && rosterClean && !versionDisagrees && clipFailures.length === 0 ? 0 : 1);
 }
 
 // ⭐ Guarded so `shapeOf`, `shapeDiff`, `skinsDeclaredBy` and `skinBlocks` can be
@@ -1638,4 +1722,4 @@ function main(): void {
 // reach either would be paying for a round trip to test arithmetic. Run as a
 // program this is unchanged: `bun tools/editor_roundtrip.ts …` makes this module
 // the entry, so `import.meta.main` is true.
-if (import.meta.main) main();
+if (import.meta.main) await main();