@rig-c/core 2.79.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.79.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/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();