@rig-c/core 2.81.0 → 2.81.1

package/NOTICE.md

@@ -8,8 +8,8 @@ Copyright (c) 2013-2025 Esoteric Software LLC, licensed under the
 [Spine Runtimes License Agreement](https://esotericsoftware.com/spine-runtimes-license),
 as a **development dependency**: a clone and CI install it, and every Spine file
 `rigc build` writes there is read back through it before it is written. **The
-published package does not carry it** — an install of `rig-c` (or of
-`spine-rigc`, the same files under the name the package first shipped as) has no
+published package does not carry it** — an install of `@rig-c/core` (or of `rig-c` or
+`spine-rigc`, the same product files under the convenience or legacy name) has no
 Spine runtime in it unless one is installed beside it, and then the same `rigc`
 uses it.
 

package/README.md

@@ -223,7 +223,7 @@ candidate chooser (`loadCandidate`, `throughPoser`), setup and animation sampler
 `rasterisePiece`, `renderFrame`), with their argument/result types and named
 failures. It loads without the optional Spine runtime; a Spine input requires
 explicitly loading `rig-c/render`, whose eager runtime dependency is unchanged.
-The promised scope and planned first minor release are in
+The promised scope and the first release (2.69.0) are in
 [RELEASING.md, The import surface](https://github.com/rig-c/core/blob/main/RELEASING.md#the-import-surface);
 [AUTHORING §0.5](docs/AUTHORING.md#05-reading-a-build-from-code) shows the call chain.
 

package/docs/AUTHORING.md

@@ -280,8 +280,13 @@ What the flags mean:
 | `--report` | `build` and `repack`: also write the gate's report as a JSON document (`build-report/1`) to this file — every gate's `PASS`, `SKIP` and `FAIL` rows, its summary figures and stats line, which supplier judged it, and every `pack:` line's figures. Written when the command writes `--out` and when a gate is red, before the exit; a file already at the path is removed first, so a compile error or a refused repack leaves none. Never inside `--out`, refused by name. The printed lines are byte-identical with it and without it — **§5.3** |
 | `--candidate` | `check`, `bench`, `render`, `inspect`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. A directory holding no `skeleton.json`, or a path with nothing at it, is refused `nothing at <path>`, exit 2, nothing written, by every command that takes a build — `validate <dir>` and a directory given to `diff` included (`RC27`). `--atlas <path>` names the atlas when it does not sit beside the skeleton. On `render` and `check` a rigc build whose `skeleton.model.json` is `rigc-compiled/3` or `/2` needs no atlas at all: with no `--atlas` and no atlas beside it, it is drawn from the document's `pages`, the same frames, geometry and figures as with it, and the `atlas` line says `— not there`. An atlas that is there is still read, and held to `pages`: one that differs (edited after the build) is drawn through spine-core, and the `poser` line names the first difference. A build drawn through an atlas that is not there — a `rigc-compiled/1` document, or a build the core refuses — is refused `nothing at <the atlas>: … is drawn through its atlas (<why>)`, exit 2, nothing written; a Spine export without its atlas is refused `nothing at <the atlas>` as it always was. A directory whose files are not one build — a `skeleton.json` or a `skeleton.atlas` from another build beside this one's `skeleton.model.json` — is drawn through spine-core where the runtime can load the pair, the `poser` line naming the two digests or the atlas's first difference; where it cannot, it is refused `<skeleton> does not load against <the atlas>: spine-core draws this pair (<the poser line's why>) and could not resolve it — "<the runtime's own words>". <dir> is not one build: …`, exit 2, nothing written (`RC18`) — another build's skeleton beside this build's atlas typically ends `"Region not found in atlas: <region> (attachment: <name>)"`. Rebuild, or put the build's own three files back beside each other. A Spine export beside an atlas it was not exported with is refused in the same words, ending `The skeleton and the atlas are not one pair`. An atlas copied from another build's directory usually stops earlier, at its pages — their paths are relative to the directory it was written in — and is refused naming the first one: `nothing at <the page>: <the atlas> names it as a page, and spine-core draws this pair through that atlas (<why>). … <dir> is not one build: …`, exit 2, nothing written (`RC18`); an export whose atlas names a page that is not there is refused the same way, ending `and the page has to be there`. A build moved or copied whole away from the directory it was built in stops at the same place, on either poser, and is refused naming the page and the file that names it: `nothing at <the page>: <the skeleton.model.json> names it as a page, and the core draws this build from it. A page path is relative to the build's directory, so a build moved or copied away from the directory it was built in names pages that are not here — build it again where it is, or build it with --copy-images, which writes its pages beside it` (under `--poser spine`, `<the atlas> names it as a page, and spine-core draws this pair through that atlas (--poser spine)` with the same ending), exit 2, nothing written (`RC21`); only where the core refused the files does a page refusal say the directory is not one build. `bench --bones` and `rigc bonedist` — on its `--candidate` and on its `--reference` — refuse a pair the runtime cannot load in the words above with `spine-core poses this pair (bonedist's candidate: …)` or `(bonedist's reference: …)`, exit 2, nothing written (`RC20`); they read no page image, so a build whose pages are elsewhere is measured as it is in place. A `skeleton.json` that is not JSON is refused `rigc: cannot read <the file>: <the parser's words> (line N, column N)`, exit 2, by `render`, `check`, `bench` and `bonedist` as by every other command that reads one (`RC22`). With the atlas gone, `check` on a `rigc-compiled/3` build reads its pages' `scale:` lines off the document, so its texture note and `check.json`'s `textureFrom.candidateScales` are what they are with the atlas; on a `/2` build its texture note says whether the atlas declares a `scale:` line is not read (that document does not state one), and `candidateScales` is `null` (`RC13`). **`vote` and `preview` take it more than once**: `vote` 2–4 times, one per pane, labelled A, B, C, D in the order given; `preview` any number of times, one pane per candidate in the order given, each headed by its path and its gate line, and the same skeleton twice (a directory and its `skeleton.json` are one) is refused by name. `--atlas` goes with one candidate only. Everywhere else a repeat is a typo and is refused |
 | `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview` (each candidate's own first, with several), and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote` and a several-candidate `preview`, so is a name that only *some* candidates have, naming the one that lacks it |
+| `--slot` | On `render`: draw only these comma-separated slot names, in draw order, on the **same grid** as the whole rig (the viewport still fits every slot). Default: all slots. Unknown names or art available only in another skin are refused by name. `frames.json` records the subset, and `check` refuses it as a reference. `split` uses this flag to name the mesh to separate — **§3.4.11** |
+| `--hide` | On `render`: draw every slot except these comma-separated names, on the same grid and with the same subset record and refusals as `--slot`. Default: hide none. Refused with `--slot` |
+| `--fps` | On `render`: frames per second to sample (default `12`, finite and at least `1`); a non-default rate writes `<anim>@<fps>fps/`, while `12` writes `<anim>/`. `bonedist` samples both skeletons at this rate (default `12`); `inspect` uses it for the `--at` grid (default `12`, **§13**); `check` uses it only for a frame set with no `frames.json` sidecar (**§9**) |
+| `--max` | `render` and `inspect`: the longest side of the frame in pixels (default `256`, finite and at least `16`). On `render`, refused with `--viewport-from`, which already fixes the pixel size — **§8.6**, **§13** |
 | `--show`, `--dim`, `--at`, `--zoom` | `inspect` only — what it draws, whether the art is faded, which times of `--animation` it poses and the bone, slot or folds it frames to; §13 says each, with the refusals |
 | `--geometry` | `render` only: also write a `geometry.json` into each frame directory — per frame, every bone's world transform and every slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry and topology, on the frames' own grid and viewport. Every other file is byte for byte what the render writes without it. Refused with `--slot`/`--hide`, because the geometry is the whole pose whatever is drawn — **§8.2** |
+| `--extremes` | `render` only: add `extremes.json` and an `EXTREMES` line per set; a moving set with comparable geometry and readable images also gets a native six-panel `extremes.png`: setup, geometry-pair min/max and three premultiplied RGBA diffs with a legend. Per-channel extrema are independent of that geometry pair; valid channels survive geometry/image SKIPs, and channel refusals are named separately. Still or uncomparable geometry is a named SKIP, with no invented pair or PNG; observation failures do not change a successful render's exit status. Supports `--slot`/`--hide` on both posers, on the whole rig's viewport. Without the flag, no extremes observations are added — **§8.11** |
 | `--folds` | `render` only: also read which mesh triangles **fold** — turn over against the setup pose — and write a `folds.json` into each frame directory: per mesh, the frames with a folded triangle, the worst frame's count and which triangles, by index, with their world box and setup-pose area. One printed line per mesh that folds; a triangle degenerate or inverted at the setup pose is said once and never counted. A reading, not a gate. Every other file is byte for byte what the render writes without it, `geometry.json` included. Refused with `--slot`/`--hide`, for `--geometry`'s reason — **§8.3** |
 | `--pass-through` | `render` only: `<cloth>:<leg>[,<cloth>:<leg>…]` — also read where each cloth slot **passes through** its leg slot, and write a `pass-through.json` into each frame directory: the frames where the cloth draws over the leg and its drawn side lies inside the leg's drawn outline by 2 steps or more, each with the depth and the world box. One printed line per pair, and one per frame that passes through. The first name must draw over the second for a frame to be read — the declared order, never both. A reading, not a gate. Every other file is byte for byte what the render writes without it. An unknown slot, a slot that draws on no frame, a malformed list and a pair named twice are refused by name, and so is `--slot`/`--hide` beside it — **§8.5** |
 | `--seam` | `render` only: `<slot>:<slot>[,<slot>:<slot>…]` — also read, for each pair, where the two drawings **stop meeting**, and write a `seam.json` into each frame directory: per pair, the frames with a **gap** (background inside the joint, where the two covered together at the setup pose) and the frames with a **ghost** (the overlap band of one showing where, from its partner's point of view, nothing was drawn), each with its cell count, area and world box, and as runs of frames with their times. One printed line per pair; a pair whose drawings share no cell at the setup pose is a **SKIP**. A reading, not a gate: the exit status never moves. Every other file is byte for byte what the render writes without it. An unknown slot, a slot with itself, a slot that draws on no frame, a malformed list and a pair named twice in either order are refused by name, and so is `--slot`/`--hide` beside it — **§8.8** |
@@ -1646,9 +1651,9 @@ written`, followed by `rigc repack: nothing was written to <out>; the work direc
 ### 0.5 Reading a build from code
 
 The named `rig-c/render-shared` entry promises the official renderer reads for
-checked consumers (issue #1561). It is planned for the next minor, 2.69.0; wait
-for the measured release before using `>=2.69.0 <3.0.0`. It requires Bun and the
-candidate's real files, but imports no optional Spine runtime. The existing
+checked consumers (issue #1561), available since 2.69.0; pin
+`>=2.69.0 <3.0.0`. It requires Bun and the candidate's real files, but imports
+no optional Spine runtime. The existing
 `rig-c/render` entry still eagerly imports that runtime.
 
 ```ts

package/docs/FACE.md

@@ -545,9 +545,9 @@ renderer must never idle-skip a mesh. Keying the pivot one link up satisfies it,
 and **the rig that satisfies the assertion is the better rig anyway.**
 
 ⚠️ **A15 assumes the meshes are mostly static, and that assumption is the rule's
-whole premise.** The `spine-html` renderer skips redrawing a mesh nothing moved, so a
-face whose `idle` breathes through one pivot keeps every mesh under it cheap only if
-nothing keys the meshes' own bones. The rule reads bone **names**: keying `headroll`
+whole premise.** The `@rig-c/play` renderer (the `rig-play` profile's player) skips
+redrawing a mesh nothing moved, so a face whose `idle` breathes through one pivot
+keeps every mesh under it cheap only if nothing keys the meshes' own bones. The rule reads bone **names**: keying `headroll`
 passes it, and `head`'s mesh still moves, because a child's world transform is
 composed from its parent's — so pivoting is right here for the anatomical reason
 above, not because it stops a redraw. A **painting rig** is the genre where the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.81.0",
+  "version": "2.81.1",
   "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-face/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-face
 description: Author a face on plain Spine data with rigc — a blink, a gaze shift, a breathing portrait and a head turn a few degrees off axis, built from deform timelines and per-part parallax. Use when the request is a talking or living portrait, a standing character, an expression or a head turn, such as "rig this face", "make the portrait blink and look around" or "turn the head". Not for Live2D file conversion, cutting a face illustration into parts, or VTuber-style real-time face tracking.
 license: MIT
-compatibility: Requires Bun 1.4 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package @rig-c/core (rig-c is the convenience name).
 ---
 
 # Face — a turn, a gaze and a blink
@@ -63,7 +63,7 @@ differential audit and the three limits it does not lift.
    rather than this closed form, and [INGEST.md](https://github.com/rig-c/core/blob/main/docs/INGEST.md) if the head
    arrived as a compiled skeleton.
 
-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/`.
 

package/skills/rigc-ingest/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-ingest
 description: Work with a Spine skeleton.json somebody else authored — exported from the Spine editor or another tool — using rigc. Read and validate it, understand a complaint rigc raised about it, decompile it into rigc specs with `rigc ingest`, normalise, re-pivot or rename it, and extend it with an animation it does not have. Use when the input is an existing skeleton.json with its .atlas and page images rather than loose part PNGs. Not for Live2D file conversion or runtime tracking.
 license: MIT
-compatibility: Requires Bun 1.4 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package @rig-c/core (rig-c is the convenience name).
 ---
 
 # Ingest — a skeleton you did not author
@@ -81,7 +81,7 @@ thing to reach for; transcription by hand is what you fall back on for a constru
 3. Then [RIGGING.md](https://github.com/rig-c/core/blob/main/docs/RIGGING.md) for why the re-pivot edit has the shape
    it has, and [MOTION.md](https://github.com/rig-c/core/blob/main/docs/MOTION.md) for the animation you are adding.
 
-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/`.
 

package/skills/rigc-motion/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-motion
 description: Author a Spine animation with rigc from key poses — an idle, a loop, a move from one picture to another — with timing and spacing, ease in and out, anticipation, arcs, overlap, follow-through, squash and stretch, and candidate variants a person can choose between. Use when the request is a movement on an existing or planned rig, in the animator's words too: "animate this rig", "make it breathe", "go from pose A to pose B", "make it feel heavier", "the cape should follow through". Not for Live2D, separating an image into parts, or real-time tracking.
 license: MIT
-compatibility: Requires Bun 1.4 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package @rig-c/core (rig-c is the convenience name).
 ---
 
 # Motion — what goes between two poses
@@ -54,7 +54,7 @@ thing that judges a movement is a person's eye through `rigc vote` — MOTION §
    head turn; [INGEST.md](https://github.com/rig-c/core/blob/main/docs/INGEST.md) if the rig arrived as a compiled
    skeleton rather than loose parts.
 
-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/`.
 

package/skills/rigc-rigging/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-rigging
 description: Decide a Spine rig's hierarchy with rigc — how many bones, where each pivot sits, what hangs off what, offsets, chains and what a chain can reach, siblings versus chains, constraints as structure — and which of those decisions the reference frames can check. Use when the request is a skeleton from loose part PNGs, such as "rig these parts", "make a Spine skeleton" or "where do the joints go", before any motion is authored. Not for Live2D, cutting an illustration into parts, or VTuber-style tracking.
 license: MIT
-compatibility: Requires Bun 1.4 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package @rig-c/core (rig-c is the convenience name).
 ---
 
 # Rigging — the hierarchy itself
@@ -52,7 +52,7 @@ are named in RIGGING §11 — neither as a pass bar.
    [INGEST.md](https://github.com/rig-c/core/blob/main/docs/INGEST.md) if the skeleton was handed to you already
    compiled.
 
-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/`.